Build/Integrations/Webhooks

Webhooks

Receive real-time notifications when events happen on your Bridge account.

Overview

Webhooks let your application receive real-time notifications when events happen on your Bridge account — payments settled, KYC verified, custody operations completed, and more.

Instead of polling the API, configure a webhook endpoint and Bridge will send a POST request whenever a relevant event occurs.

Setting Up a Webhook

1. Create an Endpoint

Create an HTTPS endpoint on your server that can receive POST requests:

POST https://your-app.com/webhooks/bridge

Your endpoint must:

Use HTTPS (HTTP is not supported)
Respond with a 2xx status code within 5 seconds
Accept JSON payloads up to 1MB

2. Register the Webhook

curl -X POST https://api.gateway.service.d.bridgeintelligence.ltd/api/v1/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/bridge",
    "events": ["payment.settled", "kyc.verified", "custody.transfer.completed"],
    "description": "Production webhook"
  }'

You'll receive a webhook secret in the response — store this securely. You'll need it to verify webhook signatures.

Event Types

Payment Events

payment.initiated — payment has been created
payment.settled — payment has reached finality
payment.failed — payment failed (insufficient funds, compliance block, etc.)

KYC Events

kyc.submitted — user has submitted KYC documents
kyc.verified — KYC verification passed
kyc.rejected — KYC verification failed
kyc.review_required — manual review required

Custody Events

custody.deposit.detected — incoming deposit detected on-chain
custody.deposit.confirmed — deposit reached confirmation threshold
custody.transfer.initiated — outgoing transfer started
custody.transfer.completed — outgoing transfer settled
custody.approval.requested — multi-sig approval requested

Wallet Events

wallet.created — new wallet created
wallet.balance_changed — wallet balance updated

Payload Format

Every webhook payload follows this structure:

{
  "id": "evt_abc123",
  "type": "payment.settled",
  "created": "2026-04-10T12:00:00Z",
  "data": {
    "object": {
      "id": "pay_xyz789",
      "amount": 50000,
      "currency": "USD",
      "status": "settled"
    }
  },
  "livemode": true
}

Signature Verification

Bridge signs every webhook with HMAC-SHA256 using your webhook secret. Verify signatures to ensure webhooks come from Bridge.

The signature is sent in the X-Bridge-Signature header:

X-Bridge-Signature: t=1712750400,v1=abc123def456...

Verification Example (Node.js)

const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const [t, v1] = signature.split(',').map(p => p.split('=')[1])
  const signedPayload = `${t}.${payload}`
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(v1),
    Buffer.from(expectedSig)
  )
}

Retries

If your endpoint returns a non-2xx status or times out, Bridge will retry the webhook with exponential backoff:

Retry 1: after 1 minute
Retry 2: after 5 minutes
Retry 3: after 30 minutes
Retry 4: after 2 hours
Retry 5: after 12 hours

After 5 failed retries, the webhook will be marked as failed and an alert will be sent to your account email.

Best Practices

Verify signatures on every incoming webhook
Respond quickly — process the webhook asynchronously after returning 200
Use idempotency — webhooks may be delivered more than once
Log everything for debugging
Use a different endpoint for sandbox vs production

← Previous

Introduction to Bridge Intelligence

Quick Start

Last updated: April 10, 2026

Got feedback?Need help?