Using webhooks

Subscribe an HTTPS endpoint, verify each delivery, and consume events idempotently. The POST body of every delivery is an Event: id, object (event), type, payload, created_at, and updated_at. List the same objects on GET /v1/events when a delivery is delayed or missed.

Register endpoints with POST /v1/webhook-subscriptions. url must be https. event_types is the filter: Rook POSTs only when the event type is in that list. Pause a subscription by setting disabled true.

Signature verification

Each endpoint has a secret that starts with whsec_. Use the entire secret string, including the prefix, as the HMAC key.

{timestamp}.{body}

Verify every delivery:

1. Read Rook-Timestamp and Rook-Signature. Reject the request if either is missing. 2. Reject the delivery if the timestamp is more than 300 seconds from the current time (replay window). 3. Compute HMAC-SHA256(secret, "{timestamp}.{body}") and hex-encode the digest (lowercase). 4. Compare the digest to each v1= value in Rook-Signature using a constant-time equality check. Succeed if any matches.

signed_payload="${timestamp}.${body}"
expected=$(printf '%s' "$signed_payload" | openssl dgst -sha256 -hmac "$webhook_secret" | awk '{print $2}')

Respond with 2xx only after the signature verifies. If verification fails, respond with 401 and do not act on the event.

Getting Started → Webhook signing covers the same scheme.

Secret rotation

POST /v1/webhook-subscriptions/{webhook_subscription_id}/secret/rotate issues a new whsec_ secret. The previous secret remains valid for 24 hours (previous_secret_expires_at). During that overlap, deliveries include two v1= signatures, comma-separated. Accept the request if either digest matches. After the window, verify only the new secret.

Retrieve the current value with GET /v1/webhook-subscriptions/{webhook_subscription_id}/secret. Treat the secret as a credential.

Retry schedule

Rook retries failed deliveries on an exponential schedule for about 24 hours. A delivery is successful when the endpoint returns 2xx. Any other HTTP status, a timeout, or a connection error is a failed try.

Respond quickly (within 10 seconds) and process work asynchronously so retries are not triggered by slow handlers.

Ordering

Deliveries are at-least-once and are not ordered. A later event may arrive before an earlier one for the same resource, and a retry may overlap a newer event.

Do not assume card.created arrives before card.updated for the same card, or that transaction.created arrives before transaction.updated. Order on created_at, then id, in your own store. The event log from GET /v1/events is newest first; walk it with page / page_size for a catch-up.

Idempotent consumption

Persist id and skip a delivery whose id you already processed. Retries, recover, replay, and resend reuse the same event id with a new webhook attempt. Acting twice on the same id duplicates work.

Webhook attempts (GET /v1/events/{event_id}/attempts and GET /v1/webhook-subscriptions/{webhook_subscription_id}/attempts) record status (PENDING, SUCCESS, FAILED), response_code, a truncated response_body, and attempted_at. They are a delivery receipt, not a substitute for storing event ids.

Event catalogue

Discriminate on type. payload is the resource snapshot named below. Retrieve always includes payload. List includes it when with_content is true (the default).