Webhooks

Bridge can POST an event to your server whenever something happens in your app: a workspace is created (a workspace, also called a tenant, is one customer account in your app), a user joins, a subscription changes, a payment fails, a quota runs out. You configure the receiving endpoint in Control Center (Bridge’s admin dashboard) on your app’s profile: the webhookUrl, an on/off switch, and an event filter that whitelists which event types you want delivered. Only event types you have subscribed to in the filter are sent.

This page covers the delivery model (envelope, signature, retries) and the REST endpoints for managing the webhook substrate: listing event types, inspecting and replaying deliveries, and rotating the signing secret.

The envelope

Every webhook is a POST to your webhookUrl with a JSON body in this shape:

{
  "id": "evt_9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c",
  "type": "subscription.plan_changed",
  "created": 1751875200,
  "app_id": "624c14cc0c01e70033356280",
  "workspace_id": "624c14cc0c01e70033356285",
  "data": {
    "workspaceId": "ws_2abc123",
    "fromPlan": "free",
    "toPlan": "pro"
  }
}

Field	Type	Description
`id`	`string`	Unique envelope ID (`evt_` prefix). Use it as your idempotency key: retries reuse the same ID, replays get a fresh one
`type`	`string`	The event type (see Event types)
`created`	`number`	Unix timestamp (seconds) when the envelope was built
`app_id`	`string`	Your app’s ID
`workspace_id`	`string?`	The workspace the event concerns, when applicable
`data`	`object`	Event-specific payload

Each request also carries these headers:

Header	Description
`Bridge-Signature`	HMAC signature, see below
`Bridge-Event-Id`	Same as the envelope `id`
`Bridge-Event-Type`	Same as the envelope `type`
`Content-Type`	`application/json`

Legacy envelope retired. The old { "events": [{ "type": "TENANT_CREATED", ... }] } batch envelope and its SCREAMING_CASE event names are no longer sent. Consumers must handle the envelope above with the dot-separated event types listed on this page.

Verifying the signature

The Bridge-Signature header is Stripe-style:

Bridge-Signature: t=1751875200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 is HMAC-SHA256(secret, "<t>.<raw body>") in hex, where secret is your app’s webhook signing secret (a whsec_... value shown in Control Center and returned by rotate secret). Signing the timestamp together with the body means a captured request cannot be replayed later: reject signatures whose t is more than 5 minutes from your current time, and compare digests with a constant-time comparison.

import { createHmac, timingSafeEqual } from 'crypto';

function verify(secret: string, header: string, rawBody: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const ageMs = Math.abs(Date.now() - Number(parts.t) * 1000);
  if (ageMs > 5 * 60 * 1000) return false;

  const expected = createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(parts.v1, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Compute the HMAC over the raw request body bytes, before any JSON parsing or re-serialization.

Retries and failure handling

Respond with any 2xx status within 10 seconds to acknowledge a delivery. Anything else (non-2xx, timeout, connection error) counts as a failed attempt, and Bridge retries with backoff:

After attempt	Next retry in
1	1 minute
2	5 minutes
3	30 minutes
4	2 hours
5	12 hours
6	24 hours
7	none: the delivery is parked as `dlq`

A delivery makes at most 7 attempts, then lands in the dead-letter queue (status: "dlq") where you can replay it manually. Pending deliveries are swept about once a minute, and each delivery’s target URL is snapshotted at dispatch time, so changing your webhookUrl does not retarget in-flight retries.

If 50 deliveries in a row exhaust their retries, Bridge automatically disables the webhook on your app and raises an operator alert. Re-enable it in Control Center once your endpoint is healthy, then replay what you missed.

Deliveries are retried independently, so events can arrive out of order and (on replay or edge cases) more than once. Deduplicate on the envelope id and use created to order.

Event types

The canonical catalogue is served by GET /webhooks/event-types. Current types:

Type	Category	Fired when
`tenant.created`	tenant	A new workspace was created in this app
`tenant.updated`	tenant	Workspace fields (name, plan, metadata) were updated
`tenant.deleted`	tenant	A workspace was deleted
`tenant_user.created`	tenant_user	A user joined a workspace (invite accepted or signup)
`tenant_user.updated`	tenant_user	A workspace user was updated (role change, profile, etc.)
`tenant_user.deleted`	tenant_user	A user left a workspace or was removed by an admin
`subscription.created`	billing	A new subscription was created for the workspace
`subscription.plan_changed`	billing	The workspace switched plans (upgrade or downgrade)
`subscription.trial_started`	billing	The workspace started a trial on a paid plan
`subscription.trial_ended`	billing	The trial period elapsed without conversion
`subscription.past_due`	billing	A renewal payment failed and the subscription is past due
`subscription.reactivated`	billing	A cancel-at-period-end subscription was reactivated
`subscription.canceled`	billing	The subscription was canceled; `endsAt` in `data` is when access ends
`payment.succeeded`	billing	A renewal or one-off invoice was paid successfully
`payment.failed`	billing	A renewal payment failed; `pastDueReason` drives messaging
`quota.exhausted`	billing	A metered quota crossed 100% of the plan limit
`entitlements.changed`	billing	The workspace entitlement set changed
`usage.drift_resolved`	billing	Reconciliation detected Bridge/Stripe usage drift and auto-healed it
`usage.drift_unrecoverable`	billing	Reconciliation exhausted retries healing drift; investigate manually

Two high-frequency SDK events, quota.updated and usage.recorded, are never delivered over webhooks. They exist only on the realtime SDK channel, so they cannot flood your endpoint.

Management endpoints

Authentication. These endpoints act on your app’s own webhook configuration and authenticate the same way as Usage & Quotas: a signed-in user’s access token plus your app ID:
Authorization: Bearer <USER_ACCESS_TOKEN>
x-app-id: <YOUR_APP_ID>
The appId path parameters must match the app in the caller’s context; a mismatch returns HTTP 400.

List event types

The full catalogue of event types Bridge can deliver, with a sample data payload for each. Control Center renders its subscription checklist from this list; use it to build your own event-filter UI or to keep consumer code in sync.

HTTP Request

GET https://api.thebridge.dev/webhooks/event-types

Response `HTTP 200`

{ "events": [...] } where each entry is:

Field	Type	Description
`type`	`string`	The event type, e.g. `subscription.canceled`
`category`	`string`	`tenant`, `tenant_user`, or `billing`
`description`	`string`	Human-readable description
`samplePayload`	`object`	Illustrative example of the envelope’s `data` field

Request example

curl --request GET 'https://api.thebridge.dev/webhooks/event-types' \
--header 'Authorization: Bearer USER_ACCESS_TOKEN' \
--header 'x-app-id: YOUR_APP_ID'

Response example (truncated):

{
  "events": [
    {
      "type": "tenant.created",
      "category": "tenant",
      "description": "A new workspace was created in this app.",
      "samplePayload": { "id": "ws_2abc123", "name": "Acme Inc.", "plan": "pro" }
    },
    {
      "type": "payment.failed",
      "category": "billing",
      "description": "A renewal payment failed. Use `pastDueReason` to drive customer-facing messaging.",
      "samplePayload": {
        "workspaceId": "ws_2abc123",
        "pastDueReason": "card_declined",
        "cardLast4": "4242"
      }
    }
  ]
}

List recent deliveries

The 20 most recent delivery records for your app, newest first, including the full payload that was (or will be) POSTed. Use this to debug a misbehaving receiver or to find dlq rows to replay.

HTTP Request

GET https://api.thebridge.dev/webhooks/deliveries/APP_ID

Path Parameters

Parameter	Type	Required	Description
`APP_ID`	`string`	Required	Your application ID. Must match the app in the caller's context

Response `HTTP 200`

An array of delivery records:

Field	Type	Description
`id`	`string`	The delivery record’s ID (use it to replay)
`eventId`	`string`	The envelope `id`
`eventType`	`string`	The envelope `type`
`targetUrl`	`string`	URL snapshotted at dispatch time
`status`	`string`	`pending`, `delivered`, `failed`, or `dlq`
`attempt`	`number`	Current attempt number (1 to 7)
`responseCode`	`number?`	HTTP status from the last attempt, or `null`
`lastError`	`string?`	Error from the last failed attempt, or `null`
`nextRetryAt`	`string?`	When the next attempt is due, or `null`
`deliveredAt`	`string?`	When the delivery succeeded, or `null`
`createdAt`	`string`	When the delivery was enqueued
`payload`	`object`	The full envelope

Request example

curl --request GET 'https://api.thebridge.dev/webhooks/deliveries/YOUR_APP_ID' \
--header 'Authorization: Bearer USER_ACCESS_TOKEN' \
--header 'x-app-id: YOUR_APP_ID'

Response example:

[
  {
    "id": "665f2c9e6d1b4f4e9d1a6a30",
    "eventId": "evt_9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c",
    "eventType": "subscription.plan_changed",
    "targetUrl": "https://your-app.example.com/bridge/webhook",
    "status": "delivered",
    "attempt": 1,
    "responseCode": 200,
    "lastError": null,
    "nextRetryAt": null,
    "deliveredAt": "2026-07-07T08:00:03.000Z",
    "createdAt": "2026-07-07T08:00:00.000Z",
    "payload": {
      "id": "evt_9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c",
      "type": "subscription.plan_changed",
      "created": 1751875200,
      "app_id": "624c14cc0c01e70033356280",
      "workspace_id": "624c14cc0c01e70033356285",
      "data": { "workspaceId": "ws_2abc123", "fromPlan": "free", "toPlan": "pro" }
    }
  }
]

Replay a delivery

Re-issue a delivery from scratch. The original record is preserved for audit; the replay creates a new delivery starting at attempt 1, with a fresh envelope id (prefixed evt_replay_) and a fresh created timestamp, sent to your current webhook configuration. Typically used on dlq rows after fixing your receiver.

HTTP Request

POST https://api.thebridge.dev/webhooks/deliveries/DELIVERY_ID/replay

Path Parameters

Parameter	Type	Required	Description
`DELIVERY_ID`	`string`	Required	The delivery record's `id` from the deliveries list. Must belong to the caller's app

Response `HTTP 201`

Field	Type	Description
`ok`	`boolean`	Always `true`
`deliveryId`	`string`	ID of the newly created delivery record

Returns HTTP 404 when the delivery does not exist.

Request example

curl --request POST 'https://api.thebridge.dev/webhooks/deliveries/665f2c9e6d1b4f4e9d1a6a30/replay' \
--header 'Authorization: Bearer USER_ACCESS_TOKEN' \
--header 'x-app-id: YOUR_APP_ID'

Response example:

{
  "ok": true,
  "deliveryId": "665f2c9e6d1b4f4e9d1a6a45"
}

Rotate the signing secret

Generate a new webhook signing secret for your app. The previous secret remains valid for a 5-minute grace window, so you can deploy the new secret to your receiver without dropping in-flight deliveries. Store the returned secret immediately; it is what you verify Bridge-Signature against.

HTTP Request

POST https://api.thebridge.dev/webhooks/secrets/rotate/APP_ID

Path Parameters

Parameter	Type	Required	Description
`APP_ID`	`string`	Required	Your application ID. Must match the app in the caller's context

Response `HTTP 201`

Field	Type	Description
`secret`	`string`	The new signing secret (`whsec_...`)
`rotatedAt`	`string`	ISO-8601 timestamp of the rotation

Request example

curl --request POST 'https://api.thebridge.dev/webhooks/secrets/rotate/YOUR_APP_ID' \
--header 'Authorization: Bearer USER_ACCESS_TOKEN' \
--header 'x-app-id: YOUR_APP_ID'

Response example:

{
  "secret": "whsec_9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "rotatedAt": "2026-07-07T08:12:00.000Z"
}

Webhooks

The envelope

Verifying the signature

Retries and failure handling

Event types

Management endpoints

List event types

HTTP Request

Response HTTP 200

List recent deliveries

HTTP Request

Path Parameters

Response HTTP 200

Replay a delivery

HTTP Request

Path Parameters

Response HTTP 201

Rotate the signing secret

HTTP Request

Path Parameters

Response HTTP 201

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 201`

Response `HTTP 201`