​

Webhook Integration (v1)

When MDB identifies a website visitor using the v1 pixel, it sends a webhook to your configured callback URL with person-level identification data. MDB uses Svix for reliable webhook delivery.

​

Quick Access

​

Getting Started

​

Step 1: Configure Your Webhook

1. Login to your MDB dashboard at mdb.tools/dash
2. Navigate to webhooks and create a new webhook endpoint
3. Add your HTTPS endpoint URL where you want to receive webhooks
4. Save your configuration

​

Step 2: Implement Webhook Handling

MDB uses Svix for webhook delivery, which provides:

• Automatic retries with exponential backoff
• Webhook signature verification for security
• Dashboard monitoring for delivery status
• Delivery logs for debugging
• Event replay capabilities

Svix Implementation Guide

Follow the comprehensive Svix guide with framework-specific examples, security best practices, and troubleshooting tips

​

Step 3: Verify Webhook Signatures

For security, always verify webhook signatures. Svix provides libraries for all major languages:

• Node.js/JavaScript - Verification guide
• Python - Verification guide
• Go - Verification guide
• Ruby, PHP, Java, Rust, and more - See all languages

​

Monitoring & Management

​

Accessing the Svix Portal

Access the Svix webhook portal to monitor and manage your webhooks:

1. Via MDB Dashboard - Go to mdb.tools/dash/pixel-wrap/webhook-portal
2. Direct Access - Visit the Svix Dashboard

​

What You Can Do in the Portal

• View event types and their payload schemas
• Monitor delivery status in real-time
• Review event logs for debugging
• Replay failed events for testing
• Track performance metrics and success rates
• Inspect payloads from actual webhook deliveries
• Configure retry settings and alerting

​

Event Types & Payloads

The v1 webhook system delivers various event types for different identification scenarios. Each event type has its own payload schema optimized for that specific use case. To view all event types and payloads:

• Visit Event Types Documentation
• Click on any event type to see its full payload schema
• Use the schema to implement type-safe webhook handlers

​

Best Practices

​

Security

• Use HTTPS - Always use secure endpoints for webhook URLs
• Verify signatures - Always verify Svix webhook signatures (guide)
• Validate payloads - Check that incoming data matches expected structure
• Monitor events - Use the Svix portal to track webhook activity

​

Reliability

• Return 2xx status codes - Any 2xx status code indicates successful receipt
• Respond quickly - Return within 30 seconds to avoid timeouts
• Process asynchronously - Don’t block webhook response with heavy processing
• Handle retries - Design endpoints to be idempotent
• Monitor delivery - Track success rates in the Svix portal

​

Implementation

• Follow Svix guides - Use the official implementation guide
• Use Svix libraries - Leverage official SDKs for signature verification
• Test thoroughly - Use the portal to replay events and test your endpoint
• Handle all event types - Be prepared for different event schemas

​

Resources

​

Troubleshooting

​

Common Issues

• Webhook not received - Check endpoint URL in your MDB dashboard
• Invalid signature - Verify you’re using the correct webhook secret from the portal
• Timeout errors - Ensure your endpoint responds within 30 seconds
• Unknown event type - Check event types documentation for current schemas

​

Getting Help

1. Check Svix logs - View detailed delivery logs in the webhook portal
2. Review Svix docs - See troubleshooting guide
3. Replay events - Test your endpoint with the replay feature in the portal
4. Contact support - Reach out to [email protected]

​

Next Steps

1. Review event types - Check the Svix Event Types to understand all available webhooks
2. Access the portal - Login to the Webhook Portal via your MDB dashboard
3. Implement webhook handling - Follow the Svix implementation guide
4. Verify signatures - Add signature verification to your endpoint
5. Test thoroughly - Use the portal to replay events and verify your implementation
6. Monitor delivery - Track webhook performance in the Svix Dashboard