Webhooks

Register a webhook

POST /v1/webhooks · scope account:write · reversible · idempotent

The response includes secret once. Verify every delivery with it: Truo-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>, and reject timestamps older than 5 minutes. The URL must be https and publicly reachable. Up to 10 webhooks per account.

curl https://api.truo.cloud/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks create

await truo.webhooks.create();

truo_webhooks({
  "action": "create"
})

operationId: webhooks.create

Delete a webhook

DELETE /v1/webhooks/{id} · scope account:write · destructive — cannot be undone · idempotent

Pending deliveries to it are dropped.

curl https://api.truo.cloud/v1/webhooks/whk_12 \
  -X DELETE \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks delete whk_12

await truo.webhooks.delete("whk_12");

truo_webhooks({
  "action": "delete",
  "id": "whk_12"
})

operationId: webhooks.delete

Get a delivery

GET /v1/webhooks/{id}/deliveries/{delivery_id} · scope account:read

curl https://api.truo.cloud/v1/webhooks/whk_12/deliveries/dlv_01JQ8X… \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks delivery whk_12 dlv_01JQ8X…

await truo.webhooks.deliveries.get("whk_12", "dlv_01JQ8X…");

truo_webhooks({
  "action": "deliveries_get",
  "id": "whk_12",
  "deliveryId": "dlv_01JQ8X…"
})

operationId: webhooks.deliveries.get

List a webhook’s deliveries

GET /v1/webhooks/{id}/deliveries · scope account:read

Newest first, with the exact signed body of each. This is where to look when a receiver disagrees.

curl https://api.truo.cloud/v1/webhooks/whk_12/deliveries \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks deliveries whk_12

await truo.webhooks.deliveries.list("whk_12");

truo_webhooks({
  "action": "deliveries_list",
  "id": "whk_12"
})

operationId: webhooks.deliveries.list

Send a delivery again

POST /v1/webhooks/{id}/deliveries/{delivery_id}/redeliver · scope account:write · reversible

Re-queues a delivered or failed delivery with the same body (and a fresh signature).

curl https://api.truo.cloud/v1/webhooks/whk_12/deliveries/dlv_01JQ8X…/redeliver \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks redeliver whk_12 dlv_01JQ8X…

await truo.webhooks.deliveries.redeliver("whk_12", "dlv_01JQ8X…");

truo_webhooks({
  "action": "deliveries_redeliver",
  "id": "whk_12",
  "deliveryId": "dlv_01JQ8X…"
})

operationId: webhooks.deliveries.redeliver

Get a webhook

GET /v1/webhooks/{id} · scope account:read

curl https://api.truo.cloud/v1/webhooks/whk_12 \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks get whk_12

await truo.webhooks.get("whk_12");

truo_webhooks({
  "action": "get",
  "id": "whk_12"
})

operationId: webhooks.get

List the account’s webhooks

GET /v1/webhooks · scope account:read

curl https://api.truo.cloud/v1/webhooks \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks list

await truo.webhooks.list();

truo_webhooks({
  "action": "list"
})

operationId: webhooks.list

Send a test event

POST /v1/webhooks/{id}/ping · scope account:write · reversible

Queues a webhook.ping delivery to this webhook only, regardless of its subscriptions. Follow it in GET /v1/webhooks/{id}/deliveries.

curl https://api.truo.cloud/v1/webhooks/whk_12/ping \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks ping whk_12

await truo.webhooks.ping("whk_12");

truo_webhooks({
  "action": "ping",
  "id": "whk_12"
})

operationId: webhooks.ping

Rotate a webhook’s signing secret

POST /v1/webhooks/{id}/rotate-secret · scope account:write · reversible

The old secret stops working immediately. Deliveries already in flight were signed with it.

curl https://api.truo.cloud/v1/webhooks/whk_12/rotate-secret \
  -X POST \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks rotate-secret whk_12

await truo.webhooks.rotate_secret("whk_12");

truo_webhooks({
  "action": "rotate_secret",
  "id": "whk_12"
})

operationId: webhooks.rotate_secret

Update a webhook

PATCH /v1/webhooks/{id} · scope account:write · reversible · idempotent

curl https://api.truo.cloud/v1/webhooks/whk_12 \
  -X PATCH \
  -H "Authorization: Bearer $TRUO_TOKEN"

truo webhooks update whk_12

await truo.webhooks.update("whk_12");

truo_webhooks({
  "action": "update",
  "id": "whk_12"
})

operationId: webhooks.update