DocsAPI DocumentationWebhooks & Event Subscriptions

Webhooks & Event Subscriptions

Receive real-time signed HTTP notifications for batch completions, address verifications, and geocodes.

Updated: August 20262 min read

Overview & Architecture

Webhooks allow your application to receive asynchronous HTTP POST events from AddressValid whenever long-running background tasks (such as large bulk CSV validation jobs) or real-time location validations complete.

Instead of polling our APIs, configure an HTTPS endpoint in the Developer Dashboard to receive instant event dispatches.

Supported Event Types

AddressValid supports the following platform events:

batch.completed: Dispatched when large CSV or automated address batch ETL finishes processing. Ideal for ingesting validated results back into your database or CRM.
batch.failed: Dispatched if an asynchronous batch import or ETL job encounters critical validation errors or corrupt files.
address.verified: Dispatched whenever an address is standardized with delivery confidence scores and structural components.
address.flagged: Dispatched when an address is flagged for ambiguity, missing components, or high risk for manual review.
geocode.completed: Dispatched when spatial coordinates (WGS84 lat/lng) and Plus Codes are resolved for a location description.

Payload Envelope Schema

Every webhook delivery is wrapped in a standard event envelope containing a unique event ID, event type, ISO timestamp, and the resource payload:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "event": "batch.completed",
  "id": "evt_9b8f2c3a1e4d",
  "timestamp": "2026-08-29T15:20:00.000Z",
  "data": {
    "jobId": "job_batch_89a1f2b4c5",
    "filename": "nigeria_merchant_addresses.csv",
    "totalRows": 2500,
    "validatedCount": 2480,
    "highConfidenceCount": 2410,
    "status": "COMPLETED",
    "completedAt": "2026-08-29T15:19:58.000Z",
    "downloadUrl": "https://addressvalid.io/batch"
  }
}

Cryptographic Signature Verification

To guarantee that incoming requests originate from AddressValid and have not been tampered with, every request contains an X-AddressValid-Signature header.

The signature is computed as an HMAC SHA-256 hash of the raw request body using your endpoint signing secret (whsec_...). Always verify the signature using constant-time comparison before processing the payload.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import crypto from 'crypto';

export function verifyWebhookSignature(
  rawBody: string | Buffer,
  signatureHeader: string,
  secret: string
): boolean {
  const computedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(signatureHeader)
  );
}

Retry Schedule & Idempotency

If your endpoint responds with a non-2xx status code (or fails to respond within 8 seconds), AddressValid automatically queues the delivery for retry with exponential backoff:

Attempt 1: Immediate dispatch
Attempt 2: +30 seconds
Attempt 3: +5 minutes
Attempt 4: +30 minutes
Attempt 5: +2 hours

Idempotency Handling

Use the X-AddressValid-Delivery header (unique per delivery) or the payload id (unique per event) to ensure your handler processes each event exactly once.

Was this documentation page helpful?

Your feedback helps us continuously improve our developer docs.

PreviousBatch Processing & ETL NextTypeScript / Node.js SDK