Skip to main content
Register an endpoint with POST /v1/webhooks. Registrations apply to matching jobs across your account. Up to 10 active endpoints are allowed, using HTTPS on port 443 and publicly reachable addresses. Redirects are not followed. Supported events are prompt.completed, prompt.failed, prompt.cancelled, prompt.paused, conversion.completed, conversion.failed, and conversion.cancelled.
Store the returned signing_secret securely. It is returned on creation and idempotent replay, not on list responses. The TypeScript equivalent is revise.webhooks.create(body, { idempotencyKey }).

​
Notification payload

Notifications contain a job reference, not document bytes or the full receipt:
Conversion events use data.conversion_id instead of data.prompt_id. A paused prompt can have content_expires_at: null. Retrieve the receipt with your API key, then download any artifacts. A completion event means succeeded; still inspect prompt partial-completion fields.

​
Verify signatures

Deliveries include webhook-id, webhook-timestamp (Unix seconds), and webhook-signature. To verify a delivery:
  1. Remove whsec_ from the signing secret and base64-decode the remainder.
  2. Use the raw request body. Don’t parse and reserialize the JSON before verifying.
  3. Compute HMAC-SHA256 over webhook-id + "." + webhook-timestamp + "." + rawBody.
  4. Base64-encode the digest and compare the v1, signature using a constant-time comparison.
  5. Check timestamp freshness and deduplicate accepted notification IDs.
A five-minute timestamp tolerance rejects stale attempts if your clocks are synchronized. Retries keep the notification ID and body but carry a fresh timestamp/signature. Each registered endpoint receives its own notification ID, so use the job ID as well when coordinating shared side effects across receivers. Verify before parsing or trusting the payload. The client package manages webhook registrations and delivery operations; receiver verification belongs to your application.

​
Acknowledgements and retries

Return 2xx within 30 seconds after durably accepting the notification. Non-2xx responses and network failures trigger retries. Deliveries can be duplicated or arrive out of order. Retrieve the job to confirm its current state. Automatic delivery makes up to 11 attempts within 24 hours. Retry delays start at 10 seconds and grow to 8 hours, with jitter. Exact delivery timing is not guaranteed. List delivery history with GET /v1/webhooks/{id}/deliveries. History lasts 30 days. exhausted deliveries can be manually retried up to three times within seven days of creation, each with its own idempotency key. Manual retries do not restore expired job content. Deleting a webhook disables it and cancels pending deliveries. An in-flight delivery may already have reached your receiver. There is no update endpoint; register a replacement if the URL or event subscriptions change.

​
Delete content after acknowledgement

Set the following on a prompt or conversion to remove its retained content after delivery:
The endpoint must belong to your account and subscribe to the matching completion event. The payload then has delete_on_acknowledgement: true. Download and durably store all required output before returning 2xx. If that cannot finish within the delivery timeout, use ordinary retention and explicitly delete content after background processing. Acknowledgement does not extend the 24-hour content deadline.