Webhooks

• Save a new connection even if the user closed the tab before reaching your callback (connection.created).
• Stop syncing data for a connection that was deleted (connection.deleted).
• Track when tokens are refreshed (connection.refreshed).
• Audit integration changes made in the dashboard (integration.*).

​

How delivery works

​

Setting up a webhook

1. Open Settings → Webhooks in the dashboard and create a webhook.
2. Enter a name (3 to 50 characters) and your endpoint’s Webhook URL. It must be publicly reachable; use HTTPS.
3. Choose the events to receive.
4. Copy the signing secret and store it with your server’s secrets. You need it to verify signatures.

​

Request format

{
  "action": "connection.created",
  "workspaceId": "cm0workspace123",
  "webhookId": "cm0webhook456",
  "webhookTimestamp": 1757700000000,
  "data": {
    "id": "conn_abc123",
    "externalId": "user_42",
    "integrationId": "cm0integration789",
    "createdAt": "2026-09-12T18:00:00.000Z",
    "updatedAt": "2026-09-12T18:00:00.000Z",
    "refreshedAt": null
  }
}

​

Writing a reliable endpoint

1. Verify the signature before trusting anything in the body. See Verifying signatures.
2. Respond within 3 seconds. Return 200 as soon as the signature checks out, then process the event asynchronously (a job queue is ideal). Slow endpoints time out and the event is lost.
3. Be idempotent. Handle the same event twice without side effects. Key your processing on action plus data.id plus the relevant timestamp.
4. Treat webhooks as hints, not the source of truth. Since deliveries aren’t retried, run a periodic job that lists connections with GET /v1/connections (filter with external_id or integration_identifier) and reconciles them with your database.
5. Monitor your endpoint. Alert on errors and slow responses in your own logs, since BundleUp doesn’t report failed deliveries.

​

Testing locally