Webhooks API

A webhook subscription tells Automette to POST to your URL whenever a matching event happens — across every render in your team, regardless of source. For one-off callbacks tied to a single render, use the webhook_url parameter on POST /api/v1/renders instead.

All subscriptions and per-request callbacks use the same payload format.

Supported events

Create a subscription

POST /api/v1/webhooks
Authorization: Bearer dg_your_api_key
Content-Type:  application/json

Request body

Response — 201

{
  "id": "cm4whk6pd0001jv04k9d5r2bj",
  "url": "https://your-app.com/hooks/automette",
  "events": ["render.completed", "render.failed"],
  "secret": "wh_...",
  "enabled": true,
  "created_at": "2026-04-22T12:00:00.000Z"
}

The secret is returned only once — store it immediately. It is used to verify the HMAC signature on every incoming payload. See Webhook payloads → signature verification.

List subscriptions

GET /api/v1/webhooks
Authorization: Bearer dg_your_api_key

Response — 200

[
  {
    "id": "cm4whk6pd0001jv04k9d5r2bj",
    "url": "https://your-app.com/hooks/automette",
    "events": ["render.completed", "render.failed"],
    "enabled": true,
    "failure_count": 0,
    "created_at": "2026-04-22T12:00:00.000Z",
    "updated_at": "2026-04-22T12:00:00.000Z"
  }
]

failure_count is the rolling count of consecutive failed delivery attempts since the last success. Automette auto-disables a subscription after 10 consecutive failures; PATCH enabled: true to re-arm it (this also resets failure_count to 0).

Get a subscription

GET /api/v1/webhooks/{id}
Authorization: Bearer dg_your_api_key

Same shape as one element of the list response.

Update a subscription

PATCH /api/v1/webhooks/{id}
Authorization: Bearer dg_your_api_key
Content-Type:  application/json

Request body

All fields optional; send only what you want to change.

Example — pause a subscription

curl -X PATCH https://automette.com/api/v1/webhooks/cm4whk6pd0001jv04k9d5r2bj \
  -H "Authorization: Bearer dg_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Send a test event

POST /api/v1/webhooks/{id}/test
Authorization: Bearer dg_your_api_key

Sends a synthetic render.completed payload to the subscription's URL immediately. Useful for verifying signature handling and endpoint connectivity before going live.

Response — 200

{ "ok": true, "status": 200 }

status echoes whatever your endpoint returned, so { "ok": false, "status": 500 } means the delivery reached your server but it errored. If your endpoint is unreachable entirely, the response is 502 with { "ok": false, "error": "..." }.

Delete a subscription

DELETE /api/v1/webhooks/{id}
Authorization: Bearer dg_your_api_key

Returns 204 No Content. Deletion is immediate and permanent — there is no soft-delete.

Errors