Webhooks Overview

Receive real-time notifications when events occur in SendPilot

Webhooks allow you to receive real-time HTTP notifications when events occur in your SendPilot workspace. Instead of polling the API, webhooks push data to your server as events happen.

How Webhooks Work

1. An event occurs in SendPilot (e.g., a lead replies to a message)
2. SendPilot sends an HTTP POST request to your webhook URL
3. Your server processes the event and returns a 2xx response
4. SendPilot marks the delivery as successful

Available Events

Message Events

• message.sent - Message sent to a lead
• message.received - Reply received from a lead

Connection Events

• connection.sent - Connection request sent
• connection.accepted - Connection accepted

Campaign Events

• campaign.started - Campaign started
• campaign.paused - Campaign paused
• campaign.resumed - Campaign resumed

Lead Events

• lead.status.changed - Lead status updated

Webhook Payload Structure

All webhook payloads follow a consistent structure:

{
  "eventId": "evt_1708456789123_abc123def",
  "eventType": "message.received",
  "timestamp": "2024-02-24T10:30:00.000Z",
  "workspaceId": "ws_abc123xyz",
  "data": {
    // Event-specific data
  }
}

Field	Type	Description
eventId	string	Unique identifier for this event (use for idempotency)
eventType	string	The type of event that occurred
timestamp	string	ISO 8601 timestamp when the event occurred
workspaceId	string	Your workspace ID
data	object	Event-specific payload data

Delivery & Retries

SendPilot uses reliable webhook delivery with automatic retries:

• Timeout: Your endpoint must respond within 30 seconds
• Success: Any 2xx response is considered successful
• Retries: Failed deliveries are retried with exponential backoff:
  • 1st retry: 5 seconds
  • 2nd retry: 30 seconds
  • 3rd retry: 2 minutes
  • 4th retry: 15 minutes
  • 5th retry: 1 hour
• Max retries: 5 attempts total

If all retries fail, the event is marked as failed. You can view failed deliveries in the SendPilot dashboard.

Security

Signature Verification

All webhook requests include a signature header for verification:

Webhook-Signature: v1,t=1708456789,s=abc123...

Verify the signature by computing HMAC-SHA256 of the request body using your webhook secret:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t=')).slice(2);
  const providedSignature = parts.find(p => p.startsWith('s=')).slice(2);
  
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(providedSignature),
    Buffer.from(expectedSignature)
  );
}

IP Allowlisting

For additional security, you can allowlist SendPilot’s webhook IPs. Contact support for the current IP ranges.

Best Practices

Respond quickly

Return a 2xx response as fast as possible. Process events asynchronously to avoid timeouts.

Handle duplicates

Use the eventId field for idempotency. The same event may be delivered multiple times in rare cases.

Verify signatures

Always verify the webhook signature to ensure the request came from SendPilot.

Log everything

Log incoming webhooks for debugging. This helps troubleshoot integration issues.

Use HTTPS

Always use HTTPS endpoints to protect sensitive data in transit.

Next Steps

Set Up Webhooks

Learn how to configure webhook subscriptions