Webhooks

Overview

Getting Started

1. 1

   Create an endpoint

   Set up an HTTP endpoint on your server that accepts POST requests. The endpoint must return a 2xx status code within 30 seconds to acknowledge receipt.

2. 2

   Register in the dashboard

   Navigate to Settings → Webhooks in your dashboard and add a new webhook. Enter your endpoint URL and select the events you want to receive.

3. 3

   Save your signing secret

   When you create a webhook, we generate a unique signing secret. Store it securely -- you will use it to verify that incoming requests are genuine.

4. 4

   Verify and process

   When a webhook arrives, verify the signature using your signing secret, then process the event payload. See the Verifying Signatures section below for implementation details.

Event Catalog

Below is the complete list of events you can subscribe to. Expand any event to view its JSON Schema or an example payload.

Webhook Headers

Every webhook delivery includes these HTTP headers:

Verifying Signatures

import crypto from "crypto";

function verifyWebhookSignature(
  rawBody: string,
  headers: Record<string, string>,
  secret: string,
): boolean {
  const webhookId = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];

  // Guard against replay attacks (5 minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - Number(timestamp)) > 300) {
    return false;
  }

  // Build the signed content
  const signedContent = `${webhookId}.${timestamp}.${rawBody}`;

  // Compute the expected signature
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedContent)
    .digest("base64");

  // Compare with timing-safe equality
  const received = signature.replace("v1,", "");
  return crypto.timingSafeEqual(
    Buffer.from(received, "base64"),
    Buffer.from(expected, "base64"),
  );
}

Retry Policy

Best Practices