Use Webhooks as Your Source of Truth

Create an endpoint

Register an HTTPS endpoint and choose the events your backend can process. Store the returned signingSecret securely; it is shown once.

curl -X POST https://api.usethrottle.dev/api/v1/webhook-endpoints \
  -H "x-api-key: $THROTTLE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://shop.example.com/api/throttle/webhook",
    "enabledEvents": ["order.created", "payment.captured", "payment.failed"]
  }'

enabledEvents must be exact event-type strings from the catalog — Throttle uses payment.captured and subscription.cancelled, not Stripe-style payment.succeeded or subscription.expired. Fetch the full list from GET /api/v1/event-types. An unknown name is rejected with 400; the error’s details[].allowedValues enumerates every accepted event type.

Verify signatures

Each delivery includes X-Throttle-Signature (format t=<unix_seconds>,v1=<hex>). Compute HMAC-SHA256 over <timestamp>.<raw body>. The verifier below also rejects deliveries whose timestamp falls outside a tolerance window (default 300s) so a captured delivery cannot be replayed indefinitely, and guards against a malformed v1 so a bad header returns false instead of throwing in your handler.

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

// Verify a Throttle webhook signature (header: "t=<unix_seconds>,v1=<hex>").
// Rejects (returns false) when the signature is invalid OR the timestamp is
// outside the tolerance window — a replayed delivery is not accepted forever.
export function verifyThrottleWebhook(
  rawBody: string,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  if (!header || typeof header !== 'string') return false;

  const parts = header.split(',').reduce((acc, kv) => {
    const idx = kv.indexOf('=');
    if (idx > 0) acc[kv.slice(0, idx).trim()] = kv.slice(idx + 1).trim();
    return acc;
  }, {} as Record<string, string>);

  const ts = parts.t ? Number.parseInt(parts.t, 10) : NaN;
  const v1 = parts.v1;
  // Guard the timestamp and require v1 to be hex — a malformed v1 would make a
  // short Buffer and timingSafeEqual would throw a RangeError, crashing your
  // handler (a malformed-header DoS).
  if (!Number.isFinite(ts) || !v1 || !/^[0-9a-f]+$/i.test(v1)) return false;

  // Reject deliveries whose timestamp is too old (or too far in the future) to
  // stop indefinite replay.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');

  // Equal-length hex strings only, then a constant-time compare.
  if (expected.length !== v1.length) return false;
  try {
    return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
  } catch {
    return false;
  }
}

Process idempotently

Webhook delivery is at-least-once. Store each event id before applying side effects so retries do not double-fulfill, double-email, or double-book revenue.

Deduping on event id covers retries. It does not cover a genuine repeat: order.created fires exactly once per order, but every other order lifecycle event is at-least-once by design, and a repeat carries a new event id. Moving an order backwards is a supported merchant action, so fulfilled → processing → fulfilled sends order.fulfilled twice. That is deliberate — a merchant who rewinds and re-fulfils has usually re-shipped, and suppressing the second event would be the one case where a shipping notification must not go missing. Make handlers that must not act twice idempotent on the entity and target state, not on the event id alone.

Abandoned carts & cart lifecycle

Carts are authoritative in Throttle. When your storefront creates a native cart (POST /api/v1/carts), Throttle tracks its whole lifecycle and detects abandonment server-side — you don't build your own timer.

• cart.abandoned — a nightly sweep marks an open cart abandoned once it sits idle past the application's configured threshold (or you can react immediately on delivery). Throttle also sends the buyer a customer.cart_abandoned recovery email when it can resolve an email and the app has recovery enabled — subscribe to the event only if you want to run your own follow-up.
• cart.converted — fires when a cart becomes an order (the successful-checkout signal, alongside order.created / payment.captured). A cart that lapses past its expires_at window is swept into cart.abandoned — there is no separate cart.expired webhook.

The cart.abandoned delivery carries the full cart so your follow-up needs no extra fetch — buyer, line items, totals, and a recoveryUrl that reopens the checkout:

{
  "id": "evt_2b8f...",
  "type": "cart.abandoned",
  "workspaceId": "9c1e...",
  "createdAt": "2026-07-04T18:22:05.000Z",
  "data": {
    "cartId": "cart_9f2a...",
    "sequence": 7,
    "currency": "USD",
    "total": 8900,
    "itemCount": 2,
    "customer": { "id": "cus_51...", "email": "[email protected]", "firstName": "Bea" },
    "lineItems": [
      { "id": "li_1", "name": "Premium Widget", "quantity": 2, "unitPrice": 2999, "total": 5998 }
    ],
    "recoveryUrl": "https://checkout.usethrottle.dev/c/cart_9f2a..."
  }
}

Payload envelope

Every delivery is a JSON object with stable top-level fields and event-specific fields under data. The signed body is capped at 256 KiB; larger deliveries are marked failed before Throttle POSTs them.

{
  "id": "evt_01HZX...",
  "type": "payment.captured",
  "version": "1",
  "workspaceId": "6659b411-9cd7-40ac-9a73-1e7801d89f55",
  "environmentId": "b7e5a40e-8c0f-4d85-a726-2ff2967f4b52",
  "createdAt": "2026-05-06T10:00:00.000Z",
  "data": {
    "paymentId": "pay_01HZX...",
    "orderId": "ord_01HZX...",
    "amount": 12900,
    "capturedAmount": 12900,
    "authorizedAmount": 12900,
    "currency": "USD",
    "customerId": "cus_01HZX...",
    "subscriptionId": "sub_01HZX...",
    "customer": {
      "id": "cus_01HZX...",
      "email": "[email protected]",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phone": null,
      "externalId": "your-user-42",
      "externalCustomerId": null
    }
  }
}

• Headers: X-Throttle-Signature, X-Throttle-Event-Id, X-Throttle-Event-Type, Content-Type: application/json.
• Envelope: id, type, version, workspaceId, environmentId, createdAt, and data.
• Amounts: all money fields are integer minor units, for example cents for USD.
• Customer identity: every subscription.* event, and every payment.* event that resolves an order, carries a nested customer object so you can map the delivery to your own user without a follow-up GET /customers/{id}. Read customer.externalId for the id you set yourself — externalCustomerId is a separate per-connection mapping and is null for most integrations. Payment events also carry customerId and, for subscription-driven charges, subscriptionId. Treat customer as optional: it is omitted when the record cannot be resolved.

Event payload reference

Each event below uses the common envelope above. Route by type and read the event fields from data.

Every order.* event embeds data.order.paymentStatus, one of pending, authorized, captured, partially_paid, partially_refunded, refunded, failed, or voided. partially_paid means money has been captured for this order, but less than the order total. Most commonly a deposit on a quote with deposit-and-balance terms, where the balance has not yet been collected.

Event scope reference

Subscribing to an event requires holding the matching read scope. When you create or update a webhook endpoint (or register an extension), every event in the requested list is checked against the registering caller's scopes; any event you are not allowed to read returns 403 with error.code = "insufficient_scopes" naming the missing scope. See the API key scopes reference for the full scope catalog and grant rules.

The full mapping is available as JSON at GET /api/v1/event-types — each entry is { type, readScope, trigger, dataShape, requiredDataKeys } , so a build step can check its handlers against the live catalogue without scraping this page. Payload shapes for every event are also typed in the @usethrottle/webhook-types package: import the ThrottleEvent discriminated union of ThrottleEventEnvelope variants and narrow on type to get the exact data shape per event.

Retries

Non-2xx responses and network failures are retried with delayed backoff and are visible in webhook delivery logs. Design handlers to return 2xx only after the event is durably stored or safely ignored as a duplicate.

The retry curve is fixed at [5m, 15m, 1h, 6h, 24h] (max five attempts). After the final attempt, deliveries are marked dead_letter and stop retrying automatically; an operator can replay them via POST /api/v1/webhook-deliveries/{deliveryId}/replay .

sequenceDiagram
  participant T as Throttle
  participant Q as Delivery Queue
  participant E as Your Endpoint
  participant Op as Operator
  T->>Q: emit event (e.g. payment.captured)
  Q->>E: attempt 1
  E-->>Q: 5xx / timeout
  Note over Q: wait 5m
  Q->>E: attempt 2
  E-->>Q: 5xx / timeout
  Note over Q: wait 15m
  Q->>E: attempt 3
  E-->>Q: 5xx / timeout
  Note over Q: wait 1h
  Q->>E: attempt 4
  E-->>Q: 5xx / timeout
  Note over Q: wait 6h
  Q->>E: attempt 5
  E-->>Q: 5xx / timeout
  Note over Q: wait 24h, max attempts reached
  Q->>Q: mark delivery dead_letter
  Op->>T: POST /api/v1/webhook-deliveries/{deliveryId}/replay
  T->>Q: requeue
  Q->>E: manual retry attempt
  E-->>Q: 2xx
  Q->>Q: mark delivered

Manage endpoints

Endpoints have three states: active, paused, and deleted. Pause stops dispatch without losing the subscription; delete is a soft remove that excludes the endpoint from the list and from future dispatch.

• PATCH /api/v1/webhook-endpoints/{id} updates url, enabledEvents, or isActive. Send { "isActive": false } to pause and { "isActive": true } to resume.
• DELETE /api/v1/webhook-endpoints/{id} soft-deletes the endpoint. Deleted endpoints cannot be recovered through the API; create a new one if you need to resubscribe.
• GET /api/v1/webhook-endpoints returns both active and paused endpoints; deleted are excluded.
• GET /api/v1/webhook-endpoints/coverage reports subscribable event types your application emitted that no active endpoint is subscribed to. A handler written for an event you never subscribed to simply never runs, and the delivery log cannot show that — it only records what was sent, so the gap is indistinguishable from the event never happening. Defaults to a 30-day window; pass ?days= (1–90) to widen it. Paused endpoints do not count as coverage. The same list appears on the webhooks page in the dashboard.
  Coverage response

  {
    "data": {
      "windowDays": 30,
      "unsubscribed": [
        {
          "type": "subscription.paused",
          "count": 12,
          "lastEmittedAt": "2026-07-27T09:24:11.000Z"
        }
      ]
    }
  }

{
  "data": {
    "id": "wep_01HZX...",
    "enabledEvents": ["payment.captured", "subscription.updated"],
    "retiredEventsIgnored": ["cart.expired"]
  }
}

Inspect deliveries

GET /api/v1/webhook-deliveries returns recent delivery attempts. Paginate via limit (1–200, default 50) and offset (default 0). Response shape is { data: { items, total, limit, offset, hasMore } } ; keep paging until hasMore is false.

Narrow the list with endpointId, status (one of pending, delivered, failed, dead_letter) and eventType (an exact event name, e.g. payment.failed). Filtering happens server-side, so status=failed returns every failed delivery across the whole result set rather than only those on the page you happened to load.

GET /api/v1/webhook-deliveries/{id} returns one delivery in full: the exact payload envelope that was signed and POSTed, its status, lastStatus/lastError, and a signatureScheme descriptor (header name, the t=…,v1=… format, and the signed {t}.{rawBody} string). Use it to debug signature verification without reverse-engineering the headers from live traffic.

This is the first place to look when something is not happening and nothing is erroring: it separates “never sent” from “sent, and your handler swallowed it”, which have identical symptoms and completely different fixes. It is also the right source for test fixtures — a mock that returns a friendlier shape than production makes tests pass while the integration is broken, so replay a captured payload rather than writing what you think the shape is. See Failures with no error.

Send a test event

POST /api/v1/webhook-endpoints/{id}/test fires a synthetic, signed delivery so you can verify reachability and signature handling. Omit the body to send a default payment.captured sample, or pass { "eventType": "subscription.renewed" } for a realistic per-event stub. To exercise your own handler logic (org lookup, subscription status updates), pass an eventType plus a data object — it is delivered verbatim as the envelope data instead of the built-in stub.