Bridge webhooks allow you to receive real-time notifications when events occur in your Bridge account. This guide covers creating, implementing, testing, and enabling webhooks using Bridge's REST API.

Prerequisites

A Bridge account with API access
Bridge API credentials (API key)
HTTPS endpoint with valid X.509 certificate
Development environment with your preferred language (Ruby, Node.js, Python, or Go)

Step 1: Create a New Webhook

First, create a webhook endpoint using the Bridge API. The webhook will be created in disabled state initially.

curl -X POST "https://api.bridge.xyz/webhooks" \
  -H "Authorization: Bearer your_bridge_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/bridge",
    "events": ["customer.created", "customer.updated"]
  }'

Response:

{
  "id": "webhook_abc123",
  "status": "disabled",
  "url": "https://your-domain.com/webhooks/bridge",
  "events": ["customer.created", "customer.updated"],
  "created_at": "2024-01-15T10:30:00Z"
}

Save the webhook_id from the response - you'll need it for testing and enabling the webhook.

Step 2: Implement the Webhook Handler

Create an endpoint that can receive and process Bridge webhook events with proper timestamp validation, refer Webhook Event Signature Verification.

Bridge webhook signatures use the format: X-Webhook-Signature: t=<timestamp>,v0=<base64-encoded-signature>

Step 3: Test the Webhook

Before enabling your webhook, test it to ensure it's working correctly.

Send a Test Event

# Send a test event to your webhook
curl -X POST "https://api.bridge.xyz/webhooks/{webhook_id}/send" \
  -H "Authorization: Bearer your_bridge_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "customer.created",
    "test_data": {
      "id": "test_customer_123",
      "email": "[email protected]"
    }
  }'

Check Webhook Logs

# View webhook delivery logs
curl -X GET "https://api.bridge.xyz/webhooks/{webhook_id}/logs" \
  -H "Authorization: Bearer your_bridge_api_key"

Get Webhook Events

# Retrieve upcoming events for the webhook
curl -X GET "https://api.bridge.xyz/webhooks/{webhook_id}/events" \
  -H "Authorization: Bearer your_bridge_api_key"

Step 4: Enable the Webhook

Once you've tested your webhook and confirmed it's working, enable it to start receiving live events.

curl -X PATCH "https://api.bridge.xyz/webhooks/{webhook_id}" \
  -H "Authorization: Bearer your_bridge_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Response:

{
  "id": "webhook_abc123",
  "status": "active",
  "url": "https://your-domain.com/webhooks/bridge",
  "events": ["customer.created", "customer.updated"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

Your webhook is now active and will receive live events from Bridge!

Security Best Practices

Always verify webhook signatures to ensure events are from Bridge
Use HTTPS endpoints with valid certificates
Store webhook secrets securely (use environment variables)
Return 200 status quickly to avoid timeouts
Implement idempotency to handle duplicate events
Log webhook events for debugging and monitoring

Common Event Types

customer.created - New customer registration
customer.updated - Customer information changes
payment.succeeded - Successful payment processing
payment.failed - Failed payment attempt
subscription.created - New subscription
subscription.cancelled - Subscription cancellation

Troubleshooting

Check webhook logs for delivery status and error messages
Verify your endpoint URL is accessible and returns 200
Ensure signature verification is implemented correctly
Check for certificate issues on your HTTPS endpoint
Monitor response times to avoid timeout issues

Next Steps

Review the Webhooks guide for more event types
Implement proper error handling and retry logic
Set up monitoring and alerting for webhook failures
Consider implementing webhook replay functionality for critical events

This completes your webhook integration with Bridge. Your application will now receive real-time notifications for customer events and can respond accordingly.