Webhook Integration (Legacy)

Legacy Version - This documentation covers the legacy webhook system. For new integrations, please use the v1 Webhooks which include Svix integration for improved reliability and security.

When MDB identifies a website visitor using the legacy pixel, it sends a webhook to your configured callback URL with person-level identification data.

Webhook Structure

MDB sends webhooks with the following JSON structure:

{
  "version": "v1",
  "options": {
    // The options object you set when loading the pixel
    "tenant_id": "client_abc123",
    "page_id": "homepage_v2",
    "source": "homepage",
    "campaign": "summer2024"
  },
  "data": {
    "person_id": "0198d25d-21b1-1aaf-2af3-f5aa289db1fa",
    "first_name": "Peter",
    "last_name": "Toth",
    // A link can be constructed: linkedin.com/in/otrtht
    "person_linkedin_id": "ptrtht",
    "headline": "Co-Founder @ Midbound | Startup Advisor | Ex Trustpilot, IBM",
    "person_address": {
      "street": "123 Main Street",
      "city": "København",
      "state": "Region Hovedstaden",
      "postal_code": "94102",
      "country": "Danmark",
      "country_code": "DK"
    },
    "ip_address": "192.168.1.100",
    "emails": [
      {
        "value": "peter@midbound.ai",
        "sub_type": "PROFESSIONAL"
      },
      {
        "value": "peter+personal@midbound.ai",
        "sub_type": "PERSONAL"
      }
    ],
    "phone_numbers": [
      {
        "value": "+45-2222-2222",
        "sub_type": "MOBILE"
      }
    ],
    "employment": {
      "current_job_title": "Co-Founder & CTO",
      "current_job_description": "Stop missing 97% of your website visitors.\nOutbound is dead and inbound isn't enough; the future is about meeting buyers in the middle. Midbound, our platform identifies those anonymous website visitors to uncover your dark funnel.",
      "current_job_start_date": "2025-05-01",
      "company": {
        "name": "Midbound",
        "overview":"Outbound tactics have become intrusive noise, while inbound strategies often leave us passively waiting for engagement. It's time to bridge the gap and connect with buyers where they are. \n\nMidbound identifies anonymous website visitors at the person and company level, enabling marketing and sales teams to uncover the dark funnel, optimize ad spend, and discover untapped markets.\n\nGet started for free at midbound.ai",
        "linkedin_id": "midbound",
        "picture_url": "https://cdn.mdb.tools/midbound.jpg",
        "website_url": "https://www.midbound.ai/",
        "industry": "Marketing and Advertising",
        "type": "Privately Held",
        "address_street": "123 Main Street",
        "address_city": "Dover",
        "address_state": "Delaware",
        "address_postal_code": "19901",
        "address_country": "United States",
        "address_country_code": "US",
        "revenue_range": "5M-10M",
        "employee_count": 3
      }
    }
  }
}

Delivery Rules

Understanding when and how webhooks are delivered:

One webhook per identified session - You receive exactly one webhook when a session with an identified visitor completes
Session-bound - Sessions are tied to both the website domain and tracking ID
Multiple sites - If you have pixels on multiple sites and the same person visits both, you’ll receive separate webhooks for each site

Session Definition

A session in MDB is defined as:

A continuous string of events with no more than 20 minutes between them
Maximum duration of 24 hours
Bound to both website and tracking ID

Webhook Scenarios

Single Site Visit

Scenario: User visits site-a.com with your pixelResult: One webhook sent when the identified session completes

Multiple Sites

Scenario: User visits both site-a.com and site-b.com (both with your pixels)Result: Two separate webhooks sent, one for each site’s session

Session Timeout

Scenario: User is active on your site, then inactive for 20+ minutesResult: Current session ends, new session starts with next activity

Extended Visit

Scenario: User stays active on your site for over 24 hoursResult: Session automatically ends at 24 hours, new session begins

Implementation Guide

Setting Up Your Webhook Endpoint

Create an HTTPS endpoint that can receive POST requests
Configure the URL in your MDB dashboard
Implement proper request handling for the webhook payload
Return appropriate HTTP status codes

Example Webhook Handler

// Express.js example
app.post('/mdb-webhook', express.json(), (req, res) => {
  const { version, options, data } = req.body;
  
  // Validate webhook
  if (version !== 'v1') {
    return res.status(400).json({ error: 'Unsupported version' });
  }
  
  // Extract tenant information for multi-tenant routing
  const tenantId = options.tenant_id;
  const pageId = options.page_id;
  
  if (!tenantId) {
    return res.status(400).json({ error: 'Missing tenant_id' });
  }
  
  // Process the identified visitor data
  console.log('Identified visitor for tenant:', tenantId, data);
  console.log('Page context:', pageId);
  console.log('Pixel options:', options);
  
  // Your processing logic here with tenant context
  processIdentifiedVisitor(data, options, tenantId);
  
  // Return success (any 2xx status code works)
  res.status(200).json({ success: true });
});

Best Practices

Always validate webhook payloads and implement proper error handling to ensure reliable data processing.

Security

Use HTTPS - Always use secure endpoints for webhook URLs
Validate payloads - Check that incoming data matches expected structure
Implement authentication - Consider implementing your own signature validation

Reliability

Return 2xx status codes - Any 2xx status code (200, 201, 204, etc.) indicates successful receipt
Non-2xx triggers retries - Any status code outside 2xx range will trigger the retry mechanism
Handle errors gracefully - Implement retry logic for failed processing on your end
Monitor webhook health - Track successful vs failed webhook deliveries

Retry Policy

MDB implements automatic retry logic for failed webhook deliveries:

Success criteria - Webhooks are considered successfully received on any 2xx HTTP status code
Failure criteria - Any non-2xx status code (3xx, 4xx, 5xx) triggers the retry mechanism
Exponential backoff - Retries with increasing delays between attempts
Maximum retry window - Retries continue for up to 5 minutes
Final status - After 5 minutes, the webhook is marked as completed even if failed

Retry Schedule Example

Attempt 1: Immediate
Attempt 2: ~2 seconds
Attempt 3: ~4 seconds  
Attempt 4: ~8 seconds
Attempt 5: ~16 seconds
...continues until 5-minute limit

Design your webhook endpoint to be idempotent since the same webhook may be delivered multiple times during retry attempts.

Data Processing

Process asynchronously - Don’t block webhook response with heavy processing
Store data safely - Ensure person-level data is handled according to privacy requirements
Use options data - Leverage the options object for routing and categorization
Extract tenant context - Use tenant_id and other identifiers for multi-tenant routing and attribution

Troubleshooting

Common Issues

Webhook not received - Check your endpoint URL and ensure it’s accessible
Invalid JSON - Verify your endpoint can handle JSON POST requests
Timeout errors - Ensure your endpoint responds quickly (< 30 seconds)

Testing

Use development URLs - Test with development webhook endpoints first
Monitor logs - Check both MDB dashboard and your server logs
Validate data structure - Ensure your code handles the webhook structure correctly

Migration to v1 Webhooks

We recommend migrating to v1 Webhooks for improved reliability and security:

Key Improvements in v1

Feature	Legacy Webhooks	v1 Webhooks
Delivery Service	Direct	Svix-powered
Signature Verification	Manual	Built-in with Svix
Monitoring Dashboard	Limited	Full Svix Dashboard
Event Replay	No	Yes
Delivery Logs	Basic	Comprehensive

Migration Steps

Update to v1 pixel - First migrate to the v1 Pixel
Get Svix webhook secret - Find it in your MDB dashboard
Implement signature verification - Add Svix verification to your endpoint
Test thoroughly - Verify webhooks are received and verified correctly
Monitor in Svix Dashboard - Use the enhanced monitoring capabilities

Next Steps

Consider migrating to v1 - Get improved reliability with Svix integration
Implement data processing - Build your logic for handling identified visitor data
Monitor performance - Track webhook delivery success rates

Quickstart (v1)

Quickstart (Legacy)

Additional Resources

Integration Examples

Webhook (Legacy)

Webhook Integration (Legacy)

Webhook Structure

Delivery Rules

Session Definition

Webhook Scenarios

Implementation Guide

Setting Up Your Webhook Endpoint

Example Webhook Handler

Best Practices

Security

Reliability

Retry Policy

Retry Schedule Example

Data Processing

Troubleshooting

Common Issues

Testing

Migration to v1 Webhooks

Key Improvements in v1

Migration Steps

Next Steps

Quickstart (v1)

Quickstart (Legacy)

Additional Resources

Integration Examples

​Webhook Integration (Legacy)

​Webhook Structure

​Delivery Rules

​Session Definition

​Webhook Scenarios

​Implementation Guide

​Setting Up Your Webhook Endpoint

​Example Webhook Handler

​Best Practices

​Security

​Reliability

​Retry Policy

​Retry Schedule Example

​Data Processing

​Troubleshooting

​Common Issues

​Testing

​Migration to v1 Webhooks

​Key Improvements in v1

​Migration Steps

​Next Steps

Webhook Integration (Legacy)

Webhook Structure

Delivery Rules

Session Definition

Webhook Scenarios

Implementation Guide

Setting Up Your Webhook Endpoint

Example Webhook Handler

Best Practices

Security

Reliability

Retry Policy

Retry Schedule Example

Data Processing

Troubleshooting

Common Issues

Testing

Migration to v1 Webhooks

Key Improvements in v1

Migration Steps

Next Steps