Webhooks

Webhooks push events from Voidhash to your server as they happen — a person is created, a subscription renews, a purchase is refunded. You register one or more HTTPS endpoints per project, pick the events each endpoint cares about, and Voidhash POSTs a signed JSON payload to your URL with automatic retries on failure.

All routes live under /api/v1/webhooks and accept any project-scoped credential — a project secret key (x-secret-key) or a user API key (x-api-key). See Authentication.

Event types

An endpoint only receives the events it subscribes to. The catalog:

Subscriptions are validated on create and update — an unknown event type is rejected with 400 Api/WebhookValidationError, and the list must contain at least one event. Test deliveries additionally use the reserved test.ping event type, which you cannot subscribe to.

The webhook endpoint object

{
  "id": "wh_ep_...",
  "projectId": "...",
  "name": "Production events",
  "url": "https://example.com/voidhash/webhooks",
  "secret": "whsec_...",
  "events": ["subscription.created", "purchase.completed"],
  "status": "active",
  "description": null,
  "consecutiveFailures": 0,
  "lastSuccessAt": "2026-07-17T09:30:00.000Z",
  "createdAt": "2026-07-01T12:00:00.000Z"
}

Setting status back to active via update also resets consecutiveFailures to 0.

Manage endpoints

Create an endpoint

POST /api/v1/webhooks/endpoints

curl https://api.voidhash.com/api/v1/webhooks/endpoints \
  -X POST \
  -H "x-secret-key: vh_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://example.com/voidhash/webhooks",
    "events": ["subscription.created", "subscription.expired", "purchase.completed"],
    "description": "Syncs entitlements into our CRM"
  }'

Returns the full endpoint object with a freshly generated secret and status: "active".

List and fetch endpoints

GET /api/v1/webhooks/endpoints
GET /api/v1/webhooks/endpoints/:endpointId

Listing returns every endpoint in the project. Fetching an unknown ID returns 404 Api/WebhookEndpointNotFoundError.

Update an endpoint

PATCH /api/v1/webhooks/endpoints/:endpointId

All fields are optional; only the ones you send change:

curl https://api.voidhash.com/api/v1/webhooks/endpoints/wh_ep_... \
  -X PATCH \
  -H "x-secret-key: vh_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

Disabled endpoints keep their configuration and delivery history but receive no new deliveries. Re-activating resets consecutiveFailures.

Delete an endpoint

DELETE /api/v1/webhooks/endpoints/:endpointId

Returns an empty success response.

Rotate the secret

POST /api/v1/webhooks/endpoints/:endpointId/rotate-secret

Generates a new whsec_ secret and returns the updated endpoint. Deliveries signed after rotation use the new secret immediately, so update your server's copy before rotating in production.

Send a test delivery

POST /api/v1/webhooks/endpoints/:endpointId/test

Enqueues a real delivery with event type test.ping and returns the delivery object (initially status: "pending"). The body your server receives is:

{
  "message": "This is a test webhook delivery",
  "timestamp": "2026-07-17T09:30:00.000Z"
}

Test deliveries go through the exact same signing, retry, and attempt-recording pipeline as real events, so they are the fastest way to verify your signature handling end to end.

Receiving deliveries

Voidhash POSTs the event payload as JSON to your endpoint URL. The event type and signature travel in headers — the body is the payload itself:

Respond with any 2xx status within 30 seconds to acknowledge the delivery. Anything else — a non-2xx status, a timeout, or a connection error — counts as a failed attempt and schedules a retry. Do your heavy processing asynchronously and acknowledge fast.

Verifying the signature

The signature is an HMAC-SHA256 over `${timestamp}.${body}` using the endpoint's secret, hex-encoded and prefixed with the scheme version v1=:

import { createHmac, timingSafeEqual } from "node:crypto";

const verifyWebhook = (rawBody: string, headers: Headers, secret: string) => {
  const timestamp = headers.get("x-webhook-timestamp");
  const signature = headers.get("x-webhook-signature");
  if (!timestamp || !signature) return false;

  const expected = `v1=${createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")}`;

  return (
    expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
};

Delivery lifecycle

Every event fan-out creates one delivery per subscribed active endpoint. A delivery moves through these statuses:

Failed attempts retry on a fixed backoff schedule: 1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours. attemptCount tracks how many attempts have run, maxAttempts is 5, and nextAttemptAt tells you when the next automatic retry fires (null once the delivery is terminal).

The delivery object

{
  "id": "wh_del_...",
  "projectId": "...",
  "webhookEndpointId": "wh_ep_...",
  "eventType": "subscription.created",
  "eventOccurredAt": "2026-07-17T09:30:00.000Z",
  "payload": { ... },
  "status": "failed",
  "attemptCount": 2,
  "maxAttempts": 5,
  "nextAttemptAt": "2026-07-17T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-07-17T09:30:00.000Z"
}

Delivery history

List deliveries

GET /api/v1/webhooks/deliveries

Returns the project's deliveries across all endpoints.

Get a delivery with attempts

GET /api/v1/webhooks/deliveries/:deliveryId

Returns the delivery plus an attempts array — one record per HTTP attempt, which is your debugging window into what your server actually returned:

Retry a delivery

POST /api/v1/webhooks/deliveries/:deliveryId/retry

Re-dispatches the delivery immediately with its original payload and returns it with status: "in_progress". Only deliveries in failed or exhausted state can be retried — anything else returns 400 Api/WebhookValidationError with the message "Can only retry failed or exhausted deliveries".

curl https://api.voidhash.com/api/v1/webhooks/deliveries/wh_del_.../retry \
  -X POST \
  -H "x-secret-key: vh_sk_..."

Errors

See API Overview for the general error shape and status mapping.