Webhooks Configuration

Webhooks Configuration

Webhooks allow your application to receive real-time HTTP callbacks when events occur in your account. Instead of polling the API, you register a URL and we push event data to it as things happen.

Setting Up a Webhook

Register a webhook endpoint by sending a POST request to /webhooks:

curl -X POST https://api.example.com/webhooks \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/receiver",
    "events": ["user.created", "user.deleted", "invoice.paid"],
    "secret": "whsec_your_signing_secret"
  }'

The events array specifies which event types trigger the webhook. Use ["*"] to subscribe to all events.

Event Types

The following event types are available for webhook subscriptions:

Payload Format

Webhook payloads are sent as JSON POST requests with the following structure:

{
  "id": "evt_1a2b3c4d5e",
  "type": "user.created",
  "timestamp": 1706140800,
  "data": {
    "user_id": "usr_abc123",
    "email": "newuser@example.com",
    "plan": "pro"
  }
}

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Verify this signature to confirm the request originated from our servers:

import crypto from "crypto";

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Always use constant-time comparison to prevent timing attacks. Reject any request where the signature does not match. Webhook deliveries that receive a non-2xx response are retried with exponential backoff up to 3 times over 24 hours.

All referenced endpoints conform to the OpenAPI 3.0 specification.