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

# Webhooks

> Receive completion events and manage deliveries.

Register an endpoint with [`POST /v1/webhooks`](/revise-api/reference/create-webhook). 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","conversion.completed"]}'
```

Store the returned `signing_secret` securely. It is returned on creation and idempotent replay, not on ordinary list responses.

## Authenticate deliveries

Deliveries include `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers. To verify a signature:

1. Remove `whsec_` from the signing secret and base64-decode the rest into key bytes.
2. Preserve the raw request body. Do not parse and reserialize JSON before verification.
3. Compute HMAC-SHA256 over the bytes of `webhook-id + "." + webhook-timestamp + "." + rawBody`.
4. Base64-encode the digest and compare the `v1,` signature using a constant-time comparison.
5. Enforce a timestamp tolerance suitable for your service and deduplicate accepted event IDs to prevent replay and duplicate processing.

Verify the signature before trusting the payload or changing application state. Your webhook signing secret is separate from the bearer API key.

## Retention and delivery management

When using `retention.delete_after_webhook_id`, the endpoint must belong to your account and subscribe to the matching completion event. **Download and durably store the result before acknowledging that completion event with 2xx**, because acknowledgement can delete its retained content.

List delivery attempts with `GET /v1/webhooks/{id}/deliveries`. Retry an eligible failed delivery explicitly with `POST /v1/webhooks/{id}/deliveries/{delivery_id}/retry` and its own idempotency key. Webhook receipt does not remove your ability to poll a job.

## TypeScript

```ts theme={null}
import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const endpoint = await revise.webhooks.create(
  {
    url: "https://example.com/hooks/revise",
    events: ["prompt.completed", "conversion.completed"],
  },
  { idempotencyKey: "completion-hook-42" },
);
```

The package manages registrations and delivery operations. Receiver signature verification belongs to your application.