Webhooks

Scopes: webhooks:read, webhooks:write

This page covers the management API. For the envelope, the signature and the retry curve, see the Webhooks guide.

Creating an endpoint

curl -X POST https://acme.krrim.com/api/v1/webhooks/endpoints/ \
  -H "Authorization: Bearer krm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://hooks.example.com/krrim",
        "description": "Ops pager",
        "events": ["task.escalated", "task.status_changed"],
        "project": 12
      }'

The signing secret is returned once, on creation. Store it — it is what you verify deliveries with, and it is not retrievable afterwards.

project is optional; omitting it subscribes across every project the caller can see.

The catalog

GET /api/v1/webhooks/catalog/

The authoritative list of event types and which are subscribable. Read it rather than hard-coding the list — that is why it is served instead of only documented.

Deliveries

GET  /api/v1/webhooks/deliveries/?endpoint=3&status=failed
GET  /api/v1/webhooks/deliveries/{id}/
POST /api/v1/webhooks/deliveries/{id}/replay/

A delivery record carries the attempt count, the response status and the error, so "why did that not arrive" is answerable without reading our logs.

Replay re-sends the original envelope and event id, not a fresh snapshot.

Testing

POST /api/v1/webhooks/endpoints/{id}/test/
POST /api/v1/webhooks/verify/

test sends a webhook.test event to that one endpoint. verify checks a signature you computed, which is the fastest way to find out that you hashed the parsed body instead of the raw bytes.

Endpoints