Webhooks

Register an endpoint with POST /v1/webhooks. Supported events are prompt.completed, prompt.failed, prompt.cancelled, prompt.paused, conversion.completed, conversion.failed, and conversion.cancelled.

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:

Remove whsec_ from the signing secret and base64-decode the rest into key bytes.
Preserve the raw request body. Do not parse and reserialize JSON before verification.
Compute HMAC-SHA256 over the bytes of webhook-id + "." + webhook-timestamp + "." + rawBody.
Base64-encode the digest and compare the v1, signature using a constant-time comparison.
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

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.

Getting started

Guides

REST reference

Authenticate deliveries

Retention and delivery management

TypeScript

​Authenticate deliveries

​Retention and delivery management

​TypeScript

Authenticate deliveries

Retention and delivery management

TypeScript