Webhooks

Overview

Webhooks notify your system when an email verification job completes or when an entire task finishes. Configure a webhook_url when creating a batch task or uploading a file. Webhook URLs must be HTTPS. You can receive two webhook types:

Per-email webhook: sent for each email as it completes (or is skipped).
Task completion webhook: sent once when the entire task finishes.

You can distinguish types by the data shape: per-email payloads include data.job, while task completion payloads include data.stats and data.jobs.

Delivery

Your endpoint receives an HTTP POST with JSON. Respond with a 2xx to acknowledge receipt. We retry on timeouts, connection errors, and 429/502/503/504 responses.

Headers

Each webhook includes:

Content-Type: application/json
User-Agent: EmailVerification/1.0
X-Webhook-ID: unique UUID per delivery
X-Webhook-Timestamp: Unix seconds when the request is sent
X-Webhook-Signature: HMAC-SHA256 of the raw request body (only when WEBHOOK_SECRET_KEY is configured). Format: sha256=<hex>

Signature verification

Compute the HMAC-SHA256 over the raw request body using your shared secret and compare to X-Webhook-Signature.

expected = "sha256=" + hex(hmac_sha256(secret, raw_body))

Payload format (HTTP request body)

All webhooks use the same outer envelope:

{
  "event_type": "email_verification_completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "completed_at": "2025-01-01T12:05:00Z",
  "data": {}
}

Field notes:

event_type is currently always email_verification_completed.
upload_id is optional and omitted in most current webhook payloads.
completed_at is when the webhook is sent (UTC).
data depends on webhook type (see below).

Per-email webhook payload

Sent once per email address. data contains the task context and a job object for the email.

{
  "event_type": "email_verification_completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "completed_at": "2025-01-01T12:01:12Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440999",
    "source": "frontend",
    "created_at": "2025-01-01T12:00:00Z",
    "updated_at": "2025-01-01T12:01:12Z",
    "job": {
      "email_address": "user@example.com",
      "status": "completed",
      "created_at": "2025-01-01T12:00:10Z",
      "updated_at": "2025-01-01T12:01:12Z",
      "email": {
        "id": "550e8400-e29b-41d4-a716-446655440222",
        "status": "valid",
        "address": "user@example.com",
        "local": "user",
        "domain": "example.com",
        "verification_steps": [
          { "step": "syntax", "status": "completed" },
          { "step": "domain", "status": "completed" },
          { "step": "smtp", "status": "completed" }
        ]
      }
    }
  }
}

Notes:

source and user_id are present when available; they may be omitted in some per-email sends.
job.email can be null or omitted if email details are unavailable.
job.skipped is included when an email is skipped.
verification_steps may be empty or omitted if no steps are recorded.

Task completion webhook payload

Sent once when all jobs for a task finish. data contains aggregated stats and the list of jobs.

{
  "event_type": "email_verification_completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "completed_at": "2025-01-01T12:05:00Z",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "550e8400-e29b-41d4-a716-446655440999",
    "source": "frontend",
    "created_at": "2025-01-01T12:00:00Z",
    "updated_at": "2025-01-01T12:05:00Z",
    "stats": {
      "total": 2,
      "pending": 0,
      "processing": 0,
      "completed": 2,
      "failed": 0
    },
    "jobs": [
      {
        "email_address": "user@example.com",
        "status": "completed",
        "created_at": "2025-01-01T12:00:10Z",
        "updated_at": "2025-01-01T12:01:12Z",
        "email": {
          "id": "550e8400-e29b-41d4-a716-446655440222",
          "status": "valid",
          "address": "user@example.com",
          "local": "user",
          "domain": "example.com",
          "verification_steps": [
            { "step": "syntax", "status": "completed" },
            { "step": "domain", "status": "completed" },
            { "step": "smtp", "status": "completed" }
          ]
        }
      },
      {
        "email_address": "ops@example.com",
        "status": "completed",
        "created_at": "2025-01-01T12:00:10Z",
        "updated_at": "2025-01-01T12:01:30Z",
        "email": {
          "id": "550e8400-e29b-41d4-a716-446655440223",
          "status": "valid",
          "address": "ops@example.com",
          "local": "ops",
          "domain": "example.com",
          "verification_steps": [
            { "step": "syntax", "status": "completed" },
            { "step": "domain", "status": "completed" },
            { "step": "smtp", "status": "completed" }
          ]
        }
      }
    ]
  }
}

Notes:

jobs can be large for big tasks; consider streaming/async processing on your side.
verification_steps may be empty or omitted if no steps are recorded.

API documentation

Authorization

Email Verification API

Reporting

Credit

Endpoint examples

Webhooks

Overview

Delivery

Headers

Signature verification

Payload format (HTTP request body)

Per-email webhook payload

Task completion webhook payload

​Overview

​Delivery

​Headers

​Signature verification

​Payload format (HTTP request body)

​Per-email webhook payload

​Task completion webhook payload

Overview

Delivery

Headers

Signature verification

Payload format (HTTP request body)

Per-email webhook payload

Task completion webhook payload