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 indisabled
state initially.
Request
Response
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
Check Webhook Logs
List upcoming webhook events
Step 4: Enable the Webhook
Once you’ve tested your webhook and confirmed it’s working, enable it to start receiving live events.Request
Response
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 registrationcustomer.updated
- Customer information changespayment.succeeded
- Successful payment processingpayment.failed
- Failed payment attemptsubscription.created
- New subscriptionsubscription.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 documentation for more details
- Implement proper error handling and retry logic
- Set up monitoring and alerting for webhook failures
- Consider implementing webhook replay functionality for critical events