Email validation webhook: automatic delivery of verification results

An email validation webhook is an HTTP request the verification service sends automatically to your server once it finishes checking an address or a list. You register a callback URL up front. The service runs the check, packages the results as JSON, and delivers them via a POST request to that URL. Your server receives the data and acts on it: updates the CRM, flags the invalid contact, triggers the next step in your automation. No one has to click anything.

This is push delivery. The alternative is polling (pull), where your application repeatedly asks the API "done yet?" A webhook removes both the lag between completion and notification and the overhead of those repeated requests.

How a validation webhook works

The flow has four steps. First, you register a callback URL in the validation service settings. This is an endpoint on your server that accepts POST requests. Second, your application submits an email address (or a list) through the API and gets back a task ID. Third, the service runs the full validation pipeline: syntax, DNS, MX record, SMTP connection, disposable mail detection, role address detection. Fourth, once that is done, the service POSTs to your callback URL with a JSON body containing the task ID and results.

Your server matches the task ID to the original request and takes action. For a single address check, it updates the contact status. For a bulk job, it either downloads the result file using the URL from the webhook payload or processes the aggregate statistics directly.

Why not just use the synchronous API?

Synchronous calls work fine for individual checks: send an address, wait 2-5 seconds, get the response. For a registration form, that is perfectly acceptable. Bulk verification of tens of thousands of addresses is a different story. Depending on list size and the number of distinct domains, a batch job can take anywhere from a few minutes to several hours.

Without a webhook, you are left with polling: send a status request every 30-60 seconds. That puts continuous load on both servers and introduces a gap. If the check finishes one second after your last poll, you wait another 29 seconds to find out. Webhooks eliminate both problems.

Webhooks are also useful for single-address checks run asynchronously. A user fills in a subscription form; you accept the address and send it for validation in the background. The user gets a confirmation immediately. When the webhook arrives, your backend updates the contact status. If the address turns out to be invalid, you flag the record and exclude it from the next send.

What the webhook request contains

For a single address check, the payload usually includes: the email being verified, a validation status (valid, invalid, risky, unknown), the reason for that status, a set of boolean flags (is_disposable, is_role, is_catch_all, is_free), and a numeric quality score. You get the same data a synchronous API call would return, only delivered to you rather than fetched by you.

Bulk jobs use a different structure. Sending results for 50,000 addresses in a single POST body is impractical. Instead, the webhook carries the task ID, aggregate statistics (counts of valid, invalid, risky, unknown), completion time, and a download URL for the full result file in CSV or JSON format. Your server fetches and processes that file after receiving the webhook.

Securing your webhook endpoint

A callback URL is an open door into your system. An unprotected endpoint lets anyone send a fake request and spoof validation results: a dead address gets marked valid, or a real customer address gets blocked. Security is not optional.

HMAC signature. The most reliable method. The validation service signs the request body with a shared secret key and passes the signature in an HTTP header. Your server computes the same signature and compares. If it does not match, reject the request. Without the key, forging the signature is not feasible.

Secret in the URL. A simpler approach: append a random token to your callback URL, for example /webhook/validate/a8f3e2b1c9d0. Only you and the validation service know this URL. Less reliable than HMAC because the URL can leak through server logs, the Referer header, or an admin panel, but adequate for basic protection.

IP allowlisting. Accept requests only from IP addresses belonging to the validation service. This works until the service changes infrastructure. Do not rely on it as the sole defense.

HTTPS. Not authentication, but a hard requirement. Webhook payloads contain email addresses, which are personal data under GDPR. Plain HTTP means any intermediary can read the contents. All callback URLs must start with https://.

Error handling, retries, and idempotency

Your server may be unavailable when a webhook arrives: a deploy, a restart, a hosting outage, a network timeout. Reliable validation services implement retry with exponential backoff: first retry after 1 minute, then 5, then 30, then 2 hours. If the endpoint never responds, the job is marked undelivered and you can request a manual resend.

Two rules on your end matter here. First, return HTTP 200 only after the data is successfully processed. If you accepted the webhook but the database write failed, return 500. The service retries, and the database may be back up by then. Returning 200 prematurely loses the data with no retry.

Second, make your endpoint idempotent. The retry mechanism means one webhook can arrive twice: the first request went through and your server processed it, but the response timed out on the sender's side, so the service considers delivery failed and sends again. Check the task ID before acting. If you already have a result for that ID, return 200 without doing anything else.

Practical use cases

Bulk list cleaning before a send. A marketer uploads a list for verification, closes the browser tab, and gets on with other work. When the job finishes, the webhook hits the company server, which updates contact statuses in the CRM and posts a Slack message or sends an email to the manager.

Async validation at signup. A user creates an account. The backend accepts the email, queues it for validation, and creates the account with status "email unverified." A few seconds later, the webhook arrives. If the address is valid, the status changes. If not, the user gets a prompt to provide a different address.

Pipeline processing. In systems where contacts arrive continuously, whether from lead generation forms or partner integrations, a webhook slots into the pipeline naturally. A new contact comes in, goes out for verification, and the webhook result determines routing: valid addresses go to the active list, invalid ones to quarantine, risky ones to a secondary review queue.

Webhook vs. polling: load comparison

Say a bulk job for 100,000 addresses takes 45 minutes. With polling every 30 seconds, your server sends 90 status requests. Eighty-nine come back "still processing"; only the last one returns actual results. With a webhook, those 90 outbound requests become one inbound POST.

At scale, the difference becomes material. Ten bulk jobs per day: polling generates around 900 requests, webhooks generate 10 inbound calls. At 100 jobs per day: 9,000 outbound vs. 100 inbound. Less traffic, less API load, less resource consumption on your server.