This guide walks you through setting up webhook subscriptions to receive real-time event notifications.Documentation Index
Fetch the complete documentation index at: https://docs.sendpilot.ai/llms.txt
Use this file to discover all available pages before exploring further.
Creating a Webhook Subscription
Via Dashboard
- Log in to your SendPilot account
- Navigate to Integrations → Webhooks
- Click Add Webhook
- Configure your webhook:
- Name: A descriptive name for this webhook
- URL: Your HTTPS endpoint that will receive events
- Events: Select which events to subscribe to
- Click Create
- Copy your webhook secret for signature verification
Via API
You can also manage webhooks programmatically through the SendPilot dashboard API.Endpoint Requirements
Your webhook endpoint must:- Accept HTTP POST requests
- Use HTTPS (HTTP is not supported for security)
- Respond with a 2xx status code within 30 seconds
- Accept JSON content type
Example Endpoint (Node.js/Express)
Example Endpoint (Python/Flask)
Testing Webhooks
Using the Test Feature
- Go to Integrations → Webhooks in the dashboard
- Find your webhook subscription
- Click Send Test Event
- Select an event type
- Check your endpoint for the test payload
Local Development
For local development, use a tunnel service to expose your local server:Managing Subscriptions
Update Events
To change which events trigger your webhook:- Go to Integrations → Webhooks
- Click on the webhook to edit
- Select or deselect event types
- Save changes
Rotate Secrets
To rotate your webhook secret:- Go to Integrations → Webhooks
- Click on the webhook to edit
- Click Rotate Secret
- Update your server with the new secret
- Confirm the rotation
After rotation, both the old and new secrets will work for 24 hours to allow for seamless updates.
Disable/Delete
To temporarily disable or permanently delete a webhook:- Go to Integrations → Webhooks
- Click on the webhook
- Toggle Enabled to disable, or click Delete to remove
Monitoring
Delivery Logs
View webhook delivery history:- Go to Integrations → Webhooks
- Click on a webhook
- View the Delivery History tab
- Event type and ID
- HTTP response code
- Response time
- Retry count (if any)
Failed Deliveries
For failed deliveries, you can:- View the error message
- See retry attempts
- Manually retry the delivery
Troubleshooting
Not receiving webhooks
Not receiving webhooks
- Verify your endpoint URL is correct and uses HTTPS
- Check that your server is publicly accessible
- Ensure the webhook is enabled
- Check server logs for incoming requests
Signature verification failing
Signature verification failing
- Verify you’re using the correct webhook secret
- Ensure you’re verifying against the raw request body
- Check that timestamps haven’t expired (5 minute tolerance)
Timeouts
Timeouts
- Ensure your endpoint responds within 30 seconds
- Process events asynchronously
- Return 200 immediately, handle logic in background
Duplicate events
Duplicate events
- Use the
eventIdfield for idempotency - Store processed event IDs in your database
- Skip events that have already been processed