Webhooks

Webhooks deliver events to your servers as they happen. They are most often used for payments, such as invoice.paid or payout.failed, but any event type can be subscribed to.

Create an endpoint

In Settings, Webhooks, add an HTTPS URL and choose the event types to send. Each endpoint has its own signing secret, prefixed whsec_.

Payload

{
  "id": "evt_01J9ZP7H3C",
  "type": "invoice.paid",
  "entity": "invoice/INV-2049",
  "actor": "system/reconciliation",
  "at": "2026-10-17T14:02:11.380Z",
  "data": { "amount": "18400.00", "currency": "EUR", "customer": "cus_Halvorsen" }
}

Verify the signature

Every request has a CL-Signature header of the form t=<unix seconds>,v1=<hex HMAC>. The HMAC is SHA-256 over <t>.<raw body> with your endpoint secret.

import crypto from 'node:crypto';

export function verify(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]));
  const t = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false; // reject replays older than 5 minutes
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Always verify against the raw request body, before any JSON parsing.

Retries

Respond with any 2xx status within 10 seconds. Otherwise we retry with exponential backoff for up to 72 hours: after 1 minute, 5 minutes, 30 minutes, 2 hours, and then every 6 hours. Events may arrive more than once or out of order; deduplicate on id and use at for ordering.

Replay

Any delivery from the last 30 days can be replayed from the console or with POST /v1/webhooks/deliveries/{id}/replay. If an endpoint fails continuously for 72 hours, it is disabled and the workspace owners are emailed.

Source IPs

Deliveries come from a fixed set of addresses per region, listed at https://api.consciouslab.xyz/v1/meta/ips, if you need to allowlist them.