Webhooks - Real-time Notifications
Real-time email validation for clean data
Configure Async Processing
Register a public HTTPS endpoint in your VeriMail dashboard to receive instant notifications when large batch validations finish processing. Webhooks bypass polling delays and trigger immediately upon job completion.
Navigate to Settings > Integrations > Webhooks and paste your endpoint URL. Select the events you want to monitor: batch.completed for successful runs, batch.failed for processing errors, and batch.rate_limit_exceeded for quota alerts. Each webhook receives a unique endpoint ID for tracking delivery status.
Dashboard Configuration
Enable webhook monitoring and assign your endpoint to specific API keys. Set a custom request timeout of 5 seconds to prevent delivery bottlenecks during peak validation windows.
Event Filtering
Filter payloads by batch size thresholds or domain categories. Only trigger notifications when processed records exceed 10,000 or when disposable email detection flags surpass 15%.
Endpoint Requirements
Your server must respond with a 200 OK status within 5 seconds. VeriMail validates SSL certificates and rejects self-signed or expired TLS configurations automatically.
JSON Event Structure
Every webhook delivers a standardized JSON payload containing batch metadata, validation metrics, and delivery confirmation tokens.
The following example shows a batch.completed event for a marketing list uploaded on November 12, 2024. All timestamps follow ISO 8601 UTC format.
Completed Batch Payload
{"webhook_id": "wh_8f3a2c1d", "event": "batch.completed", "timestamp": "2024-11-12T14:32:08Z", "batch_id": "bt_9928471", "api_key_prefix": "vk_live_88a2", "total_records": 42500, "valid": 38102, "invalid": 3148, "risky": 1250, "processing_time_ms": 18420, "credits_consumed": 42500}
Failed Batch Payload
{"webhook_id": "wh_8f3a2c1d", "event": "batch.failed", "timestamp": "2024-11-12T15:10:44Z", "batch_id": "bt_9928472", "error_code": "MALFORMED_CSV", "error_message": "Column mismatch on row 8,921. Expected 3 fields, found 5.", "retry_available": true}
Delivery Resilience & Backoff
VeriMail automatically retries failed webhook deliveries using an exponential backoff schedule to accommodate temporary server outages or maintenance windows.
Retries trigger on HTTP 5xx responses, connection timeouts, or TCP resets. The delivery sequence follows fixed intervals: 2 seconds, 8 seconds, 32 seconds, 128 seconds, and 512 seconds. After five consecutive failures, the webhook is marked as dead and archived. Failed payloads remain accessible in your dashboard event log for 24 hours, allowing manual replay or endpoint correction. Successful deliveries receive a 2xx response and are permanently logged with a unique delivery hash.
Backoff Schedule
Attempt 1: Immediate delivery. Attempt 2: +2s. Attempt 3: +8s. Attempt 4: +32s. Attempt 5: +128s. Attempt 6: +512s. Maximum retention window: 24 hours from initial trigger.
Failure Handling
Non-2xx responses outside the 5xx range (e.g., 400, 401, 404) halt retries immediately. Check your endpoint logs for malformed requests or authentication mismatches before re-enabling the webhook.
HMAC-SHA256 Payload Signing
Protect your integration endpoints by verifying that every incoming webhook originates from VeriMail's infrastructure. We sign each payload using your account's unique webhook secret.
Each request includes an X-VeriMail-Signature header containing a hex-encoded HMAC-SHA256 digest. The signature is computed over the string <timestamp>.<raw_payload> using your secret key. Reject any request where the computed signature does not match the header value or where the timestamp exceeds a 5-minute tolerance window.
Verification Steps
Extract the X-VeriMail-Signature header. Retrieve the timestamp from the payload. Concatenate as timestamp + "." + JSON.stringify(payload). Compute HMAC-SHA256 using your dashboard secret. Compare the hex output against the header value using a constant-time comparison function.
Secret Management
Rotate webhook secrets quarterly from the Integrations panel. Old secrets remain valid for 48 hours to support zero-downtime key rotation. Never expose secrets in client-side code or public repositories.