Webhooks

A subscription holds a destination URL and a list of event patterns. When a matching event happens, we POST it to your URL and sign the request. Your endpoint verifies the signature, acknowledges, and does the work.

Deliveries that fail are retried. Every attempt is recorded, so you can check what we sent and what your server answered.

Pattern forms

Subscriptions accept three pattern forms:

• *: every event
• document.generated: one exact event
• payment.*: every event under a prefix

Every delivery is a POST with Content-Type: application/json and this body:

{
  "type": "document.generated",
  "data": { },
  "timestamp": "2026-08-26T11:04:22.108Z"
}

type is the event name. data carries the event-specific fields. timestamp is ISO 8601 UTC, set when we build the payload.

Each request carries an X-Webhook-Signature header: an HMAC-SHA256 of the raw request body, keyed with your subscription secret, hex encoded. Compute the same value and compare. Reject anything that does not match.

Hash the raw bytes, not a re-serialized object. Re-encoding JSON changes key order and whitespace, which changes the hash.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header)
  );
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Use a constant-time comparison. A plain equality check leaks timing information.

Return any 2xx status to acknowledge. Anything else counts as a failure.

Acknowledge first, then do the work in a background job. Requests time out, and a slow handler turns a successful event into a retry.

Failed deliveries retry with exponential backoff:

Backoff is capped at 24 hours. After 5 attempts the delivery is marked permanently failed and is not retried again.

Returns recent attempts for one subscription.

Each record reports the event type, status, attempts, the response_code we received, any error_message, last_attempt_at, and created_at. Use it to confirm a delivery landed, or to see why it did not.

A subscription holds a destination url, an events array of patterns, an is_active flag, and the signing secret. Creating one returns the secret exactly once.

Destination URLs must be public. Private and internal addresses are rejected at create time to prevent server-side request forgery.