Webhooks

envelope.send_failed delivered to your endpoint

InkSeal sends this request to every active subscription whose events array contains envelope.send_failed, or whose events is null. Verify X-InkSeal-Signature against the raw body before doing anything else, and deduplicate on id.

postWebhookenvelope.send_failed

Headers

X-InkSeal-Event-Idstring required

The event id, identical to id in the body. Deduplicate on this.

X-InkSeal-Signaturestring required

v1= followed by the lowercase hex HMAC-SHA256 of <X-InkSeal-Timestamp>.<raw body> under the subscription's secret.

X-InkSeal-Timestampstring required

Unix seconds of this delivery attempt, as a decimal string. Part of the signed string, and the value to age-check against replay.

Payload

idstring required

Stable event id, derived from the transition rather than the clock. Every retry of this event carries the same value.

type'envelope.send_failed' required

The event type.

timestampstring date-time required

When the transition committed. Not the same as X-InkSeal-Timestamp, which is when this attempt was made.

Response

Acknowledged. Return any 2xx, with or without a body, as soon as the event is stored; do your work afterwards. Anything that is not a 2xx, including a redirect (redirects are never followed) and a response slower than the 30 second timeout, counts as a failure and is retried with exponential backoff from 60 seconds, doubling per attempt and capped at 1 hour, for at most 6 attempts. After the sixth the event is terminal and only a manual retry through POST /webhooks/{webhookId}/events/{eventId}/retry will send it again.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.