API reference

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}

The Webhook object

Attributes

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.

The Webhook object

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.succeeded"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_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.

Parameters

urlstring (URL)required
Public https:// endpoint on the default port, without embedded credentials.
eventsarray of enumsrequired
descriptionstringoptional

Returns

Returns a WebhookCreateResponse object with status 201.

Errors

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.succeeded"
  ],
  "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.succeeded"
          ],
          "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.succeeded"
    ],
    description: "A short description."
  }),
})

const data = await response.json()

Response · 201

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

List webhooks

GET/v1/webhooks

Parameters

limitinteger· queryoptional
Default: 25
cursorstring· queryoptional

Returns

Returns a WebhookList object with status 200.

Errors

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()

Response · 200

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

Retrieve a webhook

GET/v1/webhooks/{webhook_id}

Parameters

webhook_idstringrequired
Crockford-base32 ULID (26 chars).

Returns

Returns a Webhook object with status 200.

Errors

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()

Response · 200

{
  "id": "01HX5K2MZ7A3Q4FBNDC0EVDXYW",
  "url": "https://example.com/…",
  "events": [
    "task.succeeded"
  ],
  "status": "active",
  "description": "A short description.",
  "last_delivery_at": "2026-04-27T14:32:00Z",
  "created_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.

Parameters

webhook_idstringrequired
Crockford-base32 ULID (26 chars).

Body · application/json

eventsarray of enumsoptional
statusenumoptional
- active
- paused
descriptionstring, nullableoptional
rotate_secretbooleanoptional
When true, mints a fresh signing_secret and returns it once.

Returns

Returns a WebhookUpdateResponse object with status 200.

Errors

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.succeeded"
  ],
  "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.succeeded"
          ],
          "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.succeeded"
    ],
    status: "active",
    description: "A short description.",
    rotate_secret: true
  }),
})

const data = await response.json()

Response · 200

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

Delete a webhook

DELETE/v1/webhooks/{webhook_id}

Parameters

webhook_idstringrequired
Crockford-base32 ULID (26 chars).

Returns

An empty response with status 204.

Errors

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

The Webhook object

Attributes

Create a webhook

Parameters

Returns

List webhooks

Parameters

Returns

Retrieve a webhook

Parameters

Returns

Update a webhook

Parameters

Returns

Delete a webhook

Parameters

Returns