Skip to main content
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
  }
}
FieldTypeDescription
eventIdstringUnique identifier for this event (use for idempotency)
eventTypestringThe type of event that occurred
timestampstringISO 8601 timestamp when the event occurred
workspaceIdstringYour workspace ID
dataobjectEvent-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

Return a 2xx response as fast as possible. Process events asynchronously to avoid timeouts.
Use the eventId field for idempotency. The same event may be delivered multiple times in rare cases.
Always verify the webhook signature to ensure the request came from SendPilot.
Log incoming webhooks for debugging. This helps troubleshoot integration issues.
Always use HTTPS endpoints to protect sensitive data in transit.

​
Next Steps

Set Up Webhooks

Learn how to configure webhook subscriptions