Référence API

Webhooks

Customer-owned HTTPS receivers for task.*, import.* and export.* events. Deliveries are signed, retried on a backoff for six hours, and identified by a stable event id.

Endpoints

POST/v1/webhooks
GET/v1/webhooks
GET/v1/webhooks/{webhook_id}
PATCH/v1/webhooks/{webhook_id}
DELETE/v1/webhooks/{webhook_id}

L'objet Webhook

Attributs

idstring
Crockford-base32 ULID (26 chars).
urlstring (URL)
eventsarray of enums
statusenum
- active
- paused
- disabled
descriptionstring, nullable
last_delivery_attimestamp, nullable
RFC 3339 / ISO 8601 timestamp.
created_attimestamp
RFC 3339 / ISO 8601 timestamp.
updated_attimestamp
Last change to url, events, status or description.

L'objet Webhook

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.completed"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z",
  "updated_at": "2026-04-27T14:32:00Z"
}

The signing_secret in the response is shown ONCE and never returned again. Verify each delivery with HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}") and constant-time-compare to the v1 value in the Veeton-Signature header.

Paramètres

urlstring (URL)requis
Public https:// endpoint on the default port, without embedded credentials.
eventsarray of enumsrequis
descriptionstringoptionnel

Retour

Retourne un objet WebhookCreateResponse avec le statut 201.

Erreurs

400
Invalid request (URL policy, unknown event, empty events)
500
Server error

POST/v1/webhooks

curl https://api.veeton.com/v1/webhooks \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/veeton/webhook",
  "events": [
    "task.completed"
  ],
  "description": "A short description."
}'
import requests

response = requests.post(
    "https://api.veeton.com/v1/webhooks",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    json={
          "url": "https://api.example.com/veeton/webhook",
          "events": [
            "task.completed"
          ],
          "description": "A short description."
        },
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${VEETON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://api.example.com/veeton/webhook",
    events: [
      "task.completed"
    ],
    description: "A short description."
  }),
})

const data = await response.json()

Réponse · 201

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.completed"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z",
  "updated_at": "2026-04-27T14:32:00Z",
  "signing_secret": "whsec_2c7f9b41...e1"
}

List webhooks

GET/v1/webhooks

Paramètres

limitinteger· queryoptionnel
Par défaut : 25
cursorstring· queryoptionnel

Retour

Retourne un objet WebhookList avec le statut 200.

Erreurs

400
Invalid request
500
Server error

GET/v1/webhooks

curl https://api.veeton.com/v1/webhooks \
  -H "Authorization: Bearer $VEETON_KEY"
import requests

response = requests.get(
    "https://api.veeton.com/v1/webhooks",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/webhooks", {
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
})

const data = await response.json()

Réponse · 200

{
  "data": [
    {
      "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
      "url": "https://example.com/…",
      "events": [
        "task.completed"
      ],
      "status": "active",
      "description": "A short description.",
      "last_delivery_at": "2026-04-27T14:32:00Z",
      "created_at": "2026-04-27T14:32:00Z",
      "updated_at": "2026-04-27T14:32:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6InByb2RfMDFIWCJ9",
  "has_more": true
}

Retrieve a webhook

GET/v1/webhooks/{webhook_id}

Paramètres

webhook_idstringrequis
Crockford-base32 ULID (26 chars).

Retour

Retourne un objet Webhook avec le statut 200.

Erreurs

404
Not found

GET/v1/webhooks/{webhook_id}

curl https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1 \
  -H "Authorization: Bearer $VEETON_KEY"
import requests

response = requests.get(
    "https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1", {
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
})

const data = await response.json()

Réponse · 200

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.completed"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z",
  "updated_at": "2026-04-27T14:32:00Z"
}

Update a webhook

PATCH/v1/webhooks/{webhook_id}

Pass rotate_secret: true to mint a new signing_secret (returned once in the response). The previous secret is invalidated immediately — plan for a brief gap if your receiver verifies signatures synchronously during a deploy.

Paramètres

webhook_idstringrequis
Crockford-base32 ULID (26 chars).

Corps · application/json

eventsarray of enumsoptionnel
statusenumoptionnel
- active
- paused
descriptionstring, nullableoptionnel
rotate_secretbooleanoptionnel
When true, mints a fresh signing_secret and returns it once.

Retour

Retourne un objet WebhookUpdateResponse avec le statut 200.

Erreurs

404
Not found
500
Server error

PATCH/v1/webhooks/{webhook_id}

curl -X PATCH \
  https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1 \
  -H "Authorization: Bearer $VEETON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "task.completed"
  ],
  "status": "active",
  "description": "A short description.",
  "rotate_secret": true
}'
import requests

response = requests.patch(
    "https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
    json={
          "events": [
            "task.completed"
          ],
          "status": "active",
          "description": "A short description.",
          "rotate_secret": True
        },
)

print(response.json())
const response = await fetch("https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${VEETON_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    events: [
      "task.completed"
    ],
    status: "active",
    description: "A short description.",
    rotate_secret: true
  }),
})

const data = await response.json()

Réponse · 200

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.completed"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_at": "2026-04-27T14:32:00Z",
  "updated_at": "2026-04-27T14:32:00Z",
  "signing_secret": "whsec_2c7f9b41...e1"
}

Delete a webhook

DELETE/v1/webhooks/{webhook_id}

Paramètres

webhook_idstringrequis
Crockford-base32 ULID (26 chars).

Retour

Une réponse vide avec le statut 204.

Erreurs

404
Not found
500
Server error

DELETE/v1/webhooks/{webhook_id}

curl -X DELETE \
  https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1 \
  -H "Authorization: Bearer $VEETON_KEY"
import requests

response = requests.delete(
    "https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1",
    headers={"Authorization": f"Bearer {VEETON_KEY}"},
)

response.raise_for_status()
const response = await fetch("https://api.veeton.com/v1/webhooks/01HX5K2MZ7A3Q4FBNDC0EVDXY1", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${VEETON_KEY}` },
})

if (!response.ok) throw new Error(response.statusText)

Webhooks

L'objet Webhook

Attributs

Create a webhook

Paramètres

Retour

List webhooks

Paramètres

Retour

Retrieve a webhook

Paramètres

Retour

Update a webhook

Paramètres

Retour

Delete a webhook

Paramètres

Retour