Webhooks Documentation
Receive real-time notifications when email events occur. Build reactive applications that respond instantly to delivery, opens, clicks, and more.
How Webhooks Work
Event Occurs
An email is sent, delivered, opened, or bounced.
We Notify You
CalimaticMail sends a POST request to your endpoint.
You Verify
Validate the signature to ensure authenticity.
You Process
Handle the event in your application.
Webhook Payload
{
"id": "evt_1234567890",
"type": "email.delivered",
"timestamp": "2024-12-15T10:30:00Z",
"data": {
"messageId": "msg_abc123",
"from": "[email protected]",
"to": "[email protected]",
"subject": "Welcome to our platform!",
"deliveredAt": "2024-12-15T10:30:00Z",
"metadata": {
"campaignId": "welcome-series-1"
}
}
}Payload Fields
idUnique identifier for this eventtypeThe type of event that occurredtimestampISO 8601 timestamp of the eventdataEvent-specific data payloadAvailable Events
Email Events
email.sentEmail was successfully sent to the recipient serveremail.deliveredEmail was delivered to the recipient inboxemail.openedRecipient opened the emailemail.clickedRecipient clicked a link in the emailemail.bouncedEmail bounced (hard or soft bounce)email.complainedRecipient marked the email as spamInbox Events
message.receivedNew email received in a mailboxmessage.readMessage was marked as readmessage.deletedMessage was moved to trashUser Events
user.createdNew user was created in your organizationuser.updatedUser details were updateduser.deletedUser was removed from the organizationSignature Verification
Every webhook request includes a signature in the X-Calimatic-Signature header. Always verify this signature to ensure the request came from CalimaticMail.
Included Headers
X-Calimatic-SignatureX-Calimatic-TimestampX-Calimatic-Event-TypeVerification Example (Node.js)
import crypto from 'crypto';
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// In your webhook handler:
app.post('/webhooks/calimatic', (req, res) => {
const signature = req.headers['x-calimatic-signature'];
const isValid = verifyWebhookSignature(
JSON.stringify(req.body),
signature,
process.env.WEBHOOK_SECRET
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// Process the webhook...
res.status(200).send('OK');
});Retry Policy
If your endpoint returns a non-2xx status code or times out, we'll automatically retry the webhook with exponential backoff. After 6 failed attempts, the webhook will be marked as failed.
| Attempt | Delay |
|---|---|
| Attempt 1 | Immediate |
| Attempt 2 | 1 minute |
| Attempt 3 | 5 minutes |
| Attempt 4 | 30 minutes |
| Attempt 5 | 2 hours |
| Attempt 6 | 8 hours |
Successful Response
Return a 2xx status code within 30 seconds to acknowledge receipt.
Timeout
Requests timeout after 30 seconds. Process asynchronously for long operations.
Failed Webhook
After 6 retries, check the webhook logs in your dashboard to investigate.
Best Practices
Respond Quickly
Return a 200 response immediately, then process the webhook asynchronously. This prevents timeouts and unnecessary retries.
Handle Duplicates
Use the event ID for idempotency. The same event may be delivered multiple times due to retries or network issues.
Verify Signatures
Always validate the webhook signature before processing. Never trust the payload without verification.
Use HTTPS
Always use HTTPS endpoints. We do not send webhooks to HTTP endpoints for security reasons.
Ready to Get Started?
Configure your webhook endpoints from the dashboard and start receiving real-time email event notifications.