Webhooks
Receive real-time notifications when bulk jobs complete or usage thresholds are hit.
Setup
Configure your webhook URL in Settings. Webhooks are available on all plans.
When an event fires, MailSentry sends a POST request to your URL with a JSON payload.
Supported events
| Event | Description |
|---|---|
bulk.completed | A bulk validation job has finished processing. |
usage.threshold | You've used 80% of your monthly quota. |
usage.limit_reached | Monthly limit reached — requests are paused. |
test.ping | Test event sent when you click "Test Webhook" in settings. |
Payload format
{
"event": "bulk.completed",
"timestamp": "2026-04-10T12:00:04Z",
"data": {
"job_id": "job_abc123",
"total_emails": 500,
"valid": 423,
"invalid": 77
}
}Verifying signatures
Every webhook includes an X-MailSentry-Signature header — an HMAC-SHA256 of the request body using your webhook secret. Always verify this to confirm the request is genuinely from MailSentry.
import crypto from "crypto"
function verifyWebhook(body, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(body)
.digest("hex")
return signature === expected
}