Webhooks
Receive real-time notifications about email events via webhooks. Track email delivery, bounces, complaints, and more. Perfect for building responsive email tracking systems.
Available Events
Secret is Auto-Generated
If you don't provide a secret, we'll generate one for you. Save it - it's only shown once!
| Event | Description |
|---|---|
| email.sent | Email was successfully sent to the mail server |
| email.delivered | Email was successfully delivered to the recipient |
| email.bounced | Email bounced (hard or soft bounce) |
| email.complained | Recipient marked email as spam |
| email.opened | Email was opened (if tracking enabled) |
| email.clicked | Link in email was clicked (if tracking enabled) |
Select Language
# Register a webhook endpoint
curl -X POST \
https://api.sendcomms.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/webhooks/email",
"events": ["email.sent", "email.delivered", "email.bounced", "email.complained"],
"secret": "your_webhook_secret"
}'Webhook Payload
When an event occurs, we'll send a POST request to your webhook URL with the following payload:
{
"event": "email.delivered",
"transaction_id": "txn_mjgc0ejr_3ca715bfb7a0",
"timestamp": "2025-12-21T10:30:00Z",
"data": {
"id": "txn_xxx",
"email_id": "abc123-def456-789",
"type": "email",
"status": "delivered",
"to": "recipient@example.com",
"subject": "Welcome to our platform!",
"from": "hello@yourdomain.com"
}
}Registration Response
When you register a webhook, you'll receive this response. Save the secret - it's only shown once!
{
"success": true,
"data": {
"id": "e406c83c-50bc-4783-b5fc-4beafe6bf5eb",
"url": "https://your-server.com/webhooks/email",
"events": ["email.sent", "email.delivered", "email.bounced"],
"secret": "whsec_21be983f359112f9e07658ed2bddcee3...",
"active": true,
"created_at": "2025-12-21T23:25:12.006Z"
}
}Verifying Webhooks
Always verify the X-SendComms-Signature header to ensure requests are authentic:
// Node.js/Express example
const crypto = require('crypto');
app.post('/webhooks/sendcomms', (req, res) => {
const signature = req.headers['x-sendcomms-signature'];
const secret = 'whsec_your_secret_here';
const expectedSignature = 'sha256=' +
crypto.createHmac('sha256', secret)
.update(JSON.stringify(req.body))
.digest('hex');
if (signature !== expectedSignature) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process the webhook
const { event, data } = req.body;
console.log(`Received ${event} for ${data.to}`);
res.status(200).json({ received: true });
});Best Practices
Respond quickly
Return a 200 status within 5 seconds. Process events asynchronously.
Handle duplicates
Use transaction_id to deduplicate events. We may retry failed deliveries.
Use HTTPS
Webhook URLs must use HTTPS for security.
Verify signatures
Always verify the X-SendComms-Signature header to prevent spoofing.
Managing Webhooks
List Your Webhooks
curl -X GET https://api.sendcomms.com/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY"Delete a Webhook
curl -X DELETE "https://api.sendcomms.com/v1/webhooks?id=WEBHOOK_ID" \
-H "Authorization: Bearer YOUR_API_KEY"