> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive, verify, and acknowledge job status notifications.

Register an endpoint with [`POST /v1/webhooks`](/developer/docs/developer/docs/revise-api/reference/create-webhook). 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`.

```bash theme={null}
curl --fail-with-body 'https://revise.io/api/v1/webhooks' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: completion-hook-42' \
  -d '{"url":"https://example.com/hooks/revise","events":["prompt.completed","prompt.failed","conversion.completed","conversion.failed"]}'
```

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:

```json theme={null}
{
  "id": "evt_00000000-0000-4000-8000-000000000001",
  "type": "prompt.completed",
  "timestamp": "2026-09-14T12:00:00Z",
  "data": {
    "prompt_id": "prompt_00000000-0000-4000-8000-000000000002",
    "status": "succeeded",
    "delete_on_acknowledgement": false,
    "content_expires_at": "2026-09-15T12:00:00Z"
  }
}
```

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`](/developer/docs/developer/docs/revise-api/reference/list-webhook-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:

```json theme={null}
{
  "retention": {
    "delete_after_webhook_id": "wh_00000000-0000-4000-8000-000000000003"
  }
}
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.