Laneful Docs

Real-time

Events

Overview

Webhooks allow your application to receive real-time notifications about email events. Instead of polling our API, we'll send HTTP POST requests to your specified endpoint whenever events occur.

Benefits

• Real-time event notifications
• Reduced API calls and improved performance
• Automatic retry mechanism for failed deliveries
• Secure payload signing for verification

Quick Start

Adding & Configuring Webhooks

1. Access Webhook Management

Navigate to your workspace settings to manage webhooks:

Workspace → Settings → Manage Webhooks

2. Create a New Webhook

In the webhook management interface, you can:

• Click "Create Webhook" to add a new endpoint
• Enter your webhook URL (must be HTTPS)
• Select specific event types or leave empty for all events
• Copy the generated HMAC secret for signature verification
• Choose batch mode for improved performance (events sent as arrays) or disable for individual events

3. Webhook Configuration Options

Event Filtering

You can configure webhooks to receive specific event types:

• All Events: Leave event types empty to receive all webhook events
• Specific Events: Select only the event types you need (Delivery, Bounce, Open, Click, etc.)
• Multiple Webhooks: Create different webhooks for different event types

4. Batch Mode Configuration

Payload Format Options

Configure how webhook events are delivered:

• Batch Mode Enabled: Events are sent as an array for improved performance and reduced requests
• Batch Mode Disabled: Each event is sent individually as a single object
• Recommendation: Use batch mode for high-volume applications to reduce webhook calls

Webhook Structure

Payload Format

Webhook payload format depends on the batch_mode setting configured for your webhook:

Batch Mode: EnabledArray of Events

When batch mode is enabled, events are sent as an array for improved performance:

[
  {
    "email": "user@example.com",
    "event": "delivery",
    "lane_id": "5805dd85-ed8c-44db-91a7-1d53a41c86a5",
    "message_id": "H-1-019844e340027d728a7cfda632e14d0a",
    "metadata": {},
    "tag": "2-2.2-2",
    "timestamp": 1753502407
  },
  {
    "email": "user@example.com",
    "event": "open",
    "lane_id": "5805dd85-ed8c-44db-91a7-1d53a41c86a5",
    "message_id": "H-1-019844e340027d728a7cfda632e14d0b",
    "metadata": {
      "campaign_id": "camp_456",
      "user_id": "user_123"
    },
    "tag": "campaign-newsletter",
    "timestamp": 1753502500
  }
]

Batch Mode: DisabledSingle Event Object

When batch mode is disabled, each event is sent individually as a single object:

{
  "email": "user@example.com",
  "event": "delivery",
  "lane_id": "5805dd85-ed8c-44db-91a7-1d53a41c86a5",
  "message_id": "H-1-019844e340027d728a7cfda632e14d0a",
  "metadata": {},
  "tag": "2-2.2-2",
  "timestamp": 1753502407
}

Configuration

You can configure the batch mode setting when creating or editing webhooks in your dashboard: Workspace → Settings → Manage Webhooks

Event Types

The event field indicates the type of email event. Click on any event type below to see its payload structure:

Security

Webhook Signature Verification

All webhook payloads are signed with your webhook secret. Verify the signature to ensure the request is from Laneful:

const crypto = require('crypto');

function verifySignature(signature, payload, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  const signatureHash = signature.replace('sha256=', '');
  
  return crypto.timingSafeEqual(
    Buffer.from(signatureHash, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Usage
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const secret = process.env.WEBHOOK_SECRET;

if (verifySignature(signature, payload, secret)) {
  // Process the webhook events array
} else {
  // Reject the request
}

Security Best Practices

• Always verify webhook signatures
• Use HTTPS endpoints only
• Implement idempotency to handle duplicate events
• Store webhook secrets securely
• Implement rate limiting on your webhook endpoints

Testing

Test Your Webhook

1. Use ngrok for local testing

# Install ngrok
npm install -g ngrok

# Expose your local server
ngrok http 3000

# Use the ngrok URL in your webhook configuration
# https://abc123.ngrok.io/webhooks/laneful

2. Send test events

Use the webhook testing feature in your dashboard to send test events to your endpoint.

3. Monitor webhook logs

Check the webhook logs in your dashboard to see delivery status and debug any issues.

Implement Your Webhook Endpoint

1. Create a webhook endpoint

Create an endpoint in your application to receive webhook events:

// Express.js example
app.post('/webhooks/laneful', (req, res) => {
  const payload = req.body;
  
  // Verify webhook signature (recommended)
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(signature, payload)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Handle both batch and single event formats
  
  res.status(200).send('OK');
});

2. Configure webhook in dashboard

Use the webhook management interface to configure your endpoint:

Workspace → Settings → Manage Webhooks → Create Webhook

Enter your endpoint URL, select event types (optional), and save your webhook configuration.

Troubleshooting

Common Issues

Webhook not receiving events

• Verify your webhook URL is accessible from the internet
• Check that your endpoint returns a 200 status code
• Ensure your server can handle POST requests
• Check webhook logs in the dashboard for error details

Signature verification failing

• Ensure you're using the correct webhook secret
• Verify the payload is being read as raw bytes
• Check that the signature header is being read correctly
• Use timing-safe comparison for signature validation

Duplicate events

• Implement idempotency using the event ID
• Store processed event IDs to avoid reprocessing
• Return 200 status even for duplicate events

Retry Mechanism

If your webhook endpoint returns a non-2xx status code or times out, we'll retry the delivery with exponential backoff:

• Immediate retry

• 1 minute later

• 5 minutes later

• 30 minutes later

• 2 hours later

• 6 hours later

• 24 hours later

After 24 hours the webhook will be marked as failed and no further retries will be attempted.

Documentation

Webhooks

Supported Event Types

On this page