MailValid Webhooks: Results the Moment a Bulk Job Ends
Get the results posted to your app the moment a bulk job finishes. No polling.
Signed with HMAC-SHA256 · Retried up to 5 times · Bounce events free to submit
Set up in three steps
-
1
Add webhook_url to a bulk job
Tell MailValid where to post the results when the job ends.
POST /api/v1/verify/bulk { "emails": ["…"], "webhook_url": "https://your-app.com/hook" } -
2
Check the signature
Compare an HMAC-SHA256 of the raw body with the signature header.
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest() hmac.compare_digest(expected, signature) -
3
Act on the event
Use the counts, then fetch the full results from results_url.
job.completed
total_emails100valid_count85invalid_count15Fetch results_url
What each delivery tells you
The X-MailValid-Event header says what happened. Every delivery is signed with X-Mailvalid-Signature.
- job.completedFinished. Counts, credits used and a results_url.
- job.failedFailed. error_message says why.
- job.cancelledCancelled. Reserved credits were released.
Send bounces back, get sharper results
POST delivery and bounce events to /api/v1/webhooks/bounce, up to 1,000 per request. It's free.
-
deliveredMarks the address valid. -
hard_bounceMarks it invalid and clears cached results. -
soft_bounceRecorded. Mailbox full or server down. -
complaintMarks it do_not_mail. -
unsubscribeRecorded.
Three quick tips
Check the signature on the raw body, before parsing the JSON.
Your webhook secret is in the dashboard.
Failed deliveries are retried up to 5 times, with growing gaps.
Questions about MailValid for Webhooks
When does MailValid send a webhook?
When a bulk job you submitted with a webhook_url ends. The X-MailValid-Event header says how: job.completed, job.failed or job.cancelled.
How do I know a webhook really came from MailValid?
Every delivery has an X-Mailvalid-Signature header: an HMAC-SHA256 of the raw request body, signed with your account's webhook secret. Recompute it over the exact bytes you receive and compare.
Where do I find my webhook secret?
In your dashboard. It's also returned as webhook_secret from GET /api/auth/stats.
What if my endpoint is down?
Failed deliveries are retried with exponential backoff (1, 2, 4, 8 and 16 minutes), up to 5 attempts.
Does sending bounce events cost credits?
No. Submitting bounce and delivery events to the bounce webhook is free.
Stop polling. Get a webhook instead.
Create a free account, submit a bulk job with a webhook_url and get the results as soon as they're ready.
Get your free API key