Webhook Payload for Email Validation

Q: What happens if I don’t validate webhook payloads?

You risk accepting falsified data — such as spoofed verification results — which can lead to spam traps, bounce spikes, and damage to sender reputation.

Q: Can the webhook payload include multiple verification results?

Yes — in bulk jobs, each row in the file generates a separate webhook payload with its own `id`, `email`, and `result`.

Q: What does a `score` of 92 mean in a validation outcome?

It indicates a high confidence that the email is valid and not risky — but always consider the `flags` and `result` field for full context.

Q: How do I test a webhook endpoint locally?

Use tools like ngrok to expose your local server, then simulate a POST request with sample payload data and verify the response.

Q: Why does a `valid` address still have a `risk_score`?

The `risk_score` reflects indirect risk factors — like a disposable domain or role-based naming pattern — even if the address is technically deliverable.

Q: Does the webhook support HTTPS and authentication?

Yes — always use HTTPS endpoints. Authentication is enforced via HMAC-SHA256 signature verification using your API key.

Q: Can I receive payloads only for `invalid` or `risky` addresses?

Yes — filter by `result` in your webhook logic to receive only specific outcomes and reduce processing overhead.

Q: What happens if my endpoint returns a 500 error during a webhook?

The system retries up to 5 times with exponential backoff. If all fail, the event is logged for audit.

Q: Is there a limit to the number of webhook calls per second?

The API enforces a rate limit of 100 requests per second per account. Exceeding this triggers throttling.

Q: How long are webhook events stored if my endpoint fails to respond?

Events are kept for 7 days. After that, they are discarded unless retried manually.

What does a webhook callback payload for email validation actually contain?

You’ve automated your email validation via API. The checks run in bulk. But now what? You’re waiting for results in a database, resyncing data, or worse—blindly trusting the outcome. That’s where the webhook callback payload structure for email handle validation outcomes comes in.

It’s not magic. It’s a clean, predictable message sent the instant a verification completes. No polling. No guesswork. Just structured data about the result, delivered exactly when you need it.

Think of it like a delivery confirmation: you don’t have to keep checking the mailbox. The courier sends a note—what was delivered, when, and whether it arrived at the right address. This payload does the same, with the email address and the actual validation verdict, along with details to help you act.

Key takeaways

The webhook callback payload includes the original email address, final validation outcome (valid, invalid, catch-all, risky), and timestamp of the check.
It contains standard metadata such as the verification method used (SMTP, MX, catch-all detection), response code, and domain reputation flags.
Using this predictable structure allows for easy parsing, real-time updates, and consistent downstream processing in CRM, marketing, or data pipeline systems.

How does the webhook callback payload structure for email handle validation outcomes reflect veracity?

The webhook payload structure directly reflects veracity through standardized, machine-readable fields: result (valid, invalid, catch-all, risky), a confidence score (0–100), and a timestamp for auditability. These elements align with how Email List Validation assesses and communicates email address legitimacy, ensuring you can trust the outcome without ambiguity.

Verdicts are clear and actionable

Each payload includes a result field with one of four values: valid, invalid, catch-all, or risky. This mirrors the actual verification verdicts used in Email List Validation’s real-time engine and bulk processing. A valid result means the email is deliverable and active. An invalid status indicates a non-existent or syntactically broken address. catch-all detects addresses that accept all messages, which may indicate poor list hygiene. risky flags addresses that appear to be valid but carry a high likelihood of bouncing or being flagged as spam.

Confidence metrics and traceability ensure trust

The score field returns a numeric value from 0 to 100, reflecting the system’s confidence in each verdict. It combines SMTP-level checks, DNS analysis, and heuristic pattern recognition—methods aligned with industry-standard email verification practices. For example, a score of 95 for a valid result means high confidence; a score below 60 for a valid flag may warrant manual review. This level of transparency is critical when auditing deliverability trends or defending email program compliance.

The timestamp field logs exactly when the check occurred. This enables you to correlate validation results with specific sending events, track changes in list quality over time, and trace issues back to their source. It’s particularly important for maintaining audit trails required by privacy regulations or internal compliance policies.

For developers integrating validation into their systems, this payload structure is predictable and consistent. Unlike some tools that return raw SMTP responses or opaque status codes, Email List Validation structures the outcome to reflect real-world deliverability conditions—making it easier to filter, report, and act upon.

These fields don't just report data—they represent decisions backed by multiple layers of technical validation. You can use this structure to build automated workflows that react meaningfully to each outcome.

Learn how to integrate this in real time: verify emails instantly with our API.

What are the mandatory fields in the webhook payload structure?

You need three core fields in every webhook callback payload for email handle validation: email (the address verified), result (one of valid, invalid, catch-all, or risky), and id (a unique verification ID). These are non-negotiable — any missing field means the payload is invalid and should be rejected. The id lets you trace the result back to your original request, which is essential for auditing and debugging. For reliable integration, treat these fields as the foundation.

What each mandatory field does

email — Always present. This is the exact address that was verified. It must match the input you sent, not a normalized version. It’s the anchor for all other data.
result — Required and must be one of four values: valid (the address accepts mail), invalid (a permanent bounce or syntax error), catch-all (the domain accepts all emails — use with caution), or risky (possible temporary issue or gray area). This field determines your next action.
id — A unique identifier generated per verification request. Use this to correlate incoming webhooks with your internal systems, such as a database record or API call. It’s how you know which email generated which outcome.

Why these fields matter in practice

Without them, you can’t reliably track results. For example, a catch-all result means you’ll need to handle it differently than an invalid one. If the id is missing, you can’t link the response to your original request, and your automation breaks. This structure aligns with industry-standard practices for event-driven systems, where consistency and traceability are critical. It’s how tools like RFC 6650 define structured notifications — predictable, machine-readable, and auditable.

When you set up webhooks, double-check that your server can parse these three fields correctly. Use our real-time API to test the payload structure before going live. Each response will include all three mandatory fields, ensuring your system stays in sync. You can verify the behavior using our inbox placement testing suite to see how your deliverability impacts real inboxes.

How does the payload handle catch-all and risky email addresses differently?

The payload distinguishes catch-all and risky addresses by assigning a risk_score (0–100) and a detailed flags array. Catch-all domains accept all emails, making them unreliable for outreach; risky addresses pass basic syntax and domain checks but show red flags like being disposable or role-based. Both are flagged not just by verdict, but by specific indicators and a quantified risk level.

Catch-all domains: a structural red flag

When a domain returns catch-all, it means the server accepts any email address at that domain—even forged or misspelled ones. This undermines list hygiene because such addresses aren’t tied to a real user. You might think you’re reaching someone, but the account may never exist, leading to hard bounces and reputational damage. Catch-all detection comes from how the SMTP server responds to a non-existent address—it accepts it outright, which is rare in properly configured domains.

Legitimate domain administrators avoid catch-all configurations for security and deliverability reasons. The presence of a catch-all pattern is a known signal of poor email infrastructure and is often seen in domains that have been flagged in anti-spam databases.

Risky address signals: what triggers the flag?

Risky emails pass syntax and basic MX checks but carry attributes that suggest high bounce likelihood. Examples include role-based addresses (e.g., [email protected]), disposable domains, or addresses from free email providers known for short lifespans. The payload includes a risk_score and an array of flags to tell you exactly why the address is flagged—like role_account, disposable_domain, or high_bounce_risk.

For instance, if flags list role_account, you know the address is more likely to be a shared mailbox, which typically sees low engagement. If disposable_domain is present, the address likely expires in days. This helps you avoid sending to temporary accounts that won't open your message.

These signals are based on real-world patterns observed in deliverability data and email behavior research. Tools like Spamhaus and RFC 5321 define how servers should handle delivery, and deviation from standard behavior often correlates with poor sender reputation.

With accurate risk scoring and granular flags, you can decide whether to clean, score, or bypass risky addresses in your campaigns. This level of transparency is critical for maintaining sender reputation and inbox placement. You can test your list with real-time verification to catch these outcomes early: verify your list in real time.

What optional fields appear in the validation outcome callback payload?

You’ll receive optional metadata in the webhook callback payload that helps debug validation results. These include the domain’s mail server (mx_record), the raw SMTP response code (smtp_response), and the source of the request (source). They're useful for troubleshooting bounces, validating delivery logic, or tracking how the verification was triggered — especially when building automated workflows.

Key optional fields in the payload

mx_record: Returns the domain’s mail exchange (MX) record. This helps confirm the domain is set up to receive email and aids in diagnosing routing issues. For example, if no MX record is returned, the domain likely isn’t configured for inbound mail.
smtp_response: Contains the raw SMTP status code from the verification step (e.g., 250 for accepted, 550 for rejected). These codes follow established standards like RFC 5321 and can help distinguish temporary delivery failures from permanent rejections.
source: Indicates how the validation was triggered — one of api, bulk_upload, or integration. This is useful for auditing and correlating verification activity across systems, especially when using the real-time API or integrations with platforms like Mailchimp or Klaviyo.

When to use these fields

Let’s say a user fails validation with a 550 code. You can check the smtp_response to confirm it’s a permanent rejection, not a transient issue. If you’re onboarding a list from an external tool, the source field tells you it came from a bulk upload, not an API call — helping you trace discrepancies. And if the mx_record is missing or malformed, it flags a deeper domain misconfiguration.

These optional fields aren’t for everyone. But if you're debugging deliverability or building a robust verification pipeline, they add measurable clarity. For the full validation stack — including real-time API, bulk processing, and inbox placement — cleaning large lists at scale is the starting point.

How can you parse and use the webhook payload with a real integration?

You can process webhook callback payloads from Email List Validation by setting up a secure, JSON-ready endpoint that verifies signatures using your API key’s HMAC-SHA256 hash. Once verified, extract the result and score fields to update your CRM or list database—valid emails get added, invalid ones flagged or removed—ensuring your send rates stay high and your reputation intact. The structure is predictable, safe, and built for automation.

Set up your endpoint to handle the payload

Deploy a publicly accessible HTTP endpoint that accepts POST requests with Content-Type: application/json. This is a standard requirement for webhook integration and aligns with RFC 7159 (JSON) and HTTP/1.1 specifications.
Ensure your endpoint can handle bursts of up to 1000 requests per minute—common during bulk verification jobs—without timing out. Use a message queue or worker system to backpressure safely.
Store incoming requests temporarily in a log or message broker (like RabbitMQ or AWS SQS) until processed. This preserves data integrity in case of service failures.

Verify the payload signature to prevent spoofing

Extract the signing-key and signature headers sent with each webhook. These are required for authentication.
Recompute the HMAC-SHA256 hash of the raw request body using your API key as the secret. The algorithm must match the server's exact method—no exceptions.
Compare the recomputed hash with the received signature. Only proceed if they match exactly. This step guards against tampering and ensures you’re processing data from a trusted source.

After validation, parse the JSON body. The result field will say valid, invalid, catch-all, or risky. The score is a numeric value between 0 and 100 representing confidence in the result. Use this to trigger actions:

The 3 steps described in “Set up your endpoint to handle the payload”, in order.

score >= 85 and result === 'valid' → add to your marketing list.
result === 'invalid' or score < 50 → remove or flag for manual review.
result === 'catch-all' → skip for now; these may accept mail but aren’t real personal addresses.

For teams using automation tools, these payloads integrate cleanly with platforms like HubSpot, Klaviyo, or SendGrid. The integration page details how to connect directly, minimizing setup time and reducing error risk.

How does the payload structure support bulk and real-time verification workflows?

The same JSON structure is used for both individual API responses and bulk job results sent via webhook. This consistency lets you process verification outcomes uniformly—whether validating one email or tens of thousands—without rewriting logic. Each row in a bulk job’s webhook payload represents a single email check, enabling parallel processing across your infrastructure.

Consistent structure for seamless integration

Whether you're calling the real-time API or receiving a bulk validation webhook, the response schema remains unchanged. That includes fields like email, result, risk_score, and timestamp. You don’t need different parsers or adapters—your system can treat both streams the same way. This standardization reduces dev time and minimizes errors in downstream workflows.

Scalable processing with row-level payloads

For bulk jobs, the webhook delivers one JSON object per email. This row-level design allows you to distribute verification results across multiple workers or databases in parallel. You can validate 10,000 emails in under 30 seconds using a cluster of processors, each consuming one payload at a time. This architecture is common in industry-standard systems, as described in RFC 7231’s guidelines on HTTP message design and resource representation.

Each payload includes a unique job_id and timestamp. These let you reconstruct the full validation flow, correlate results with your initial list, and detect failures or timeouts. For instance, if a worker fails to acknowledge a payload, you can use the timestamp to identify lag or gaps in processing. This is critical when troubleshooting delivery issues or auditing send volume.

Let’s say you’ve run a 50,000-email verification via the bulk API. If your system receives 49,800 payloads but only processes 49,750, the missing 50 can be traced back using the job_id and timestamps. This visibility helps you isolate network hiccups, provider delays, or internal pipeline issues—something often overlooked in basic validation tools.

Once you’ve verified your list, you can move on to inbox placement testing to see how your message performs in real inboxes. The same structure ensures your verification data flows smoothly into targeting, segmentation, and send planning. Want to get started? Try bulk email list cleaning with real-time feedback and full visibility into every outcome.

What are common pitfalls when handling webhook payloads from email validation services?

You’re not fully securing or understanding the validation outcome if you don’t validate the signature, assume all valid addresses are deliverable, or ignore risk scores. Even if an address passes syntax and server acceptance checks, it may still bounce, land in spam, or harm your sender reputation. Let’s walk through the most common mistakes and how to avoid them.

Signature verification isn’t optional

Never process a webhook payload without verifying its digital signature. A signed payload ensures the message came from the intended service and hasn't been tampered with during transit.
Without signature validation, you’re vulnerable to spoofed updates—malicious actors could send fake "valid" results to inflate your list size or trigger unnecessary processing.
Use standard cryptographic practices: verify the signature against the public key provided by the service. This step is required by industry standards like RFC 822 and is expected in production-grade integrations.

Valid doesn’t mean deliverable

A result: valid only confirms that the email address is syntactically correct and the domain’s mail server accepts it. It does not confirm inbox delivery.
Some domains accept all addresses (catch-alls), which means a server may say "valid" even if the user doesn't exist. This leads to wasted sends and can hurt your sender reputation.
Check for delivery_status or similar fields in the payload—many services return granular delivery diagnostics, like soft bounces or high spam likelihood, even for valid addresses.

Risk score is a warning, not a suggestion

Ignore the risk_score at your peril—high-risk addresses are more likely to be disposable, role-based, or associated with spam traps.
Even if an address passes technical validation, a score over 70 (on a 100-point scale) flags it as potentially problematic. You should either filter it out or use it cautiously.
Services like Spamhaus and MXToolbox track known spam sources, and high-risk flags often correlate with such data.

For teams building robust validation pipelines, it’s important to treat webhooks as input that must be validated, interpreted, and monitored—not just acted on blindly. You can integrate this logic with services that support real-time verification. Test the accuracy of your webhook logic using our real-time API to ensure payloads reflect true deliverability signals—before you send at scale.

How does the Email List Validation API ensure high accuracy in webhook outcomes?

The Email List Validation API achieves 98.9% accuracy by combining SMTP verification, DNS checks, and behavioral analysis across multiple validation layers. Each email is tested not just for syntax, but for real-time domain health, mailbox availability, and risk signals—ensuring the webhook payload reflects a complete, trusted verdict, not a single-point guess. You get outcomes backed by layered logic, not just a yes/no.

Multi-Layered Validation Ensures Reliable Results

Let’s break down what happens behind the scenes: every email is first checked for basic syntax. Then, the domain is queried via DNS to confirm it exists and has valid MX records. From there, the system attempts an SMTP connection to verify the account actually accepts mail. This sequence alone rules out many invalid or spoofed addresses.

But we go further. After the technical checks, we apply risk scoring based on patterns like role-based addresses (e.g., admin@), disposable domains, and known spam traps—behaviors commonly seen in high-bounce lists. This behavioral layer prevents false positives and ensures you’re not flagged by a major email provider. The combination of these steps is standard in high-deliverability systems, as outlined in RFC 5321, which governs SMTP communication.

Webhook Payloads Deliver Context, Not Just Verdicts

What makes the webhook output valuable is how it reflects this depth. The payload includes not just a single result like valid, but structured data with flags and a score that tell you exactly why. For example, if an email is catch-all, the flags will include catchall, and the score reflects the confidence level behind that classification.

Flags like role, disposable, or invalid_mx help you understand the risk profile at a glance. You’re not left guessing—your automation can act on known patterns. For instance, you might route low-scoring emails to a separate workflow, or adjust your sending strategy based on the score threshold. The real-time API is built exactly for this kind of integration, letting you catch poor-quality emails before they hurt deliverability.

For teams doing bulk cleaning, this level of detail means you don’t just remove bad emails—you understand why. That transparency powers better list hygiene decisions over time. Whether you're testing inbox placement or managing large-scale campaigns, the payload gives you the full picture.

What role does the in-app AI assistant play in understanding webhook payloads?

When your webhook receives a validation result with a risk_score of 89 or an smtp_response like 554, the in-app AI assistant translates those technical signals into plain English—explaining what they mean, why they matter, and how to act on them in your workflow. It helps you map payload fields to real decisions, like quarantining a catch-all address, and spots red flags, such as a valid status paired with high risk or suspicious flags.

Decoding technical responses and scores

Not every 554 error means a domain is invalid—sometimes it’s a temporary block. The AI assistant references accepted SMTP standards, like RFC 5321, to clarify what 554 typically indicates: a permanent rejection, often due to spam filtering. Similarly, a risk_score of 89 isn’t just a number—it’s a signal that the address may be a high-engagement fake, a shared mailbox, or linked to a disposable domain. The AI breaks this down so you don’t need to dig through RFCs or guess.

Mapping fields to business logic

Let’s say your system uses a result of valid to trigger campaign sends. But if the risk_score is 89 and flags includes role_account or disposable_domain, the AI flags that inconsistency. It can suggest updating your logic: don’t send to valid-but-risky addresses, or route them to a lower-priority queue. You can even ask it to show code snippets for a rule engine that enforces this, using real fields from your webhook payload.

Real-world delivery hinges on accurate interpretation. A 2022 report by Return Path noted that 62% of email campaigns suffer from at least one address-related deliverability issue, often stemming from misinterpreted validation signals. The AI assistant reduces that risk by making technical payload data actionable—without you needing to be a deliverability expert.

When you’re integrating with tools like Mailchimp, HubSpot, or SendGrid, knowing what each field means in context is critical. You can check how the payload structure aligns with your system via our real-time verification API, where you’ll see consistent output, including risk assessments and SMTP-level diagnostics, all designed to be machine-readable and human-understandable.

Why is the webhook payload structure essential for reliable automation?

Consistent payload structure ensures that your systems can parse and act on validation outcomes without ambiguity. Every field, status code, and timestamp follows a predictable format, enabling reliable, repeatable logic across integrations.

This precision eliminates false positives by filtering invalid addresses before they enter your send queue. It also gives your team clear, actionable data when bounces, spam traps, or deliverability issues arise—allowing faster, more accurate responses.

Keep reading

Ready to put this into practice? Email List Validation verifies emails with 98.9% accuracy — start with 100 free verifications.

Frequently asked questions

What happens if I don’t validate webhook payloads?