Webhooks

Webhooks allow you to receive validation results in real-time without polling the API. This is especially useful for async batch validations or keeping your local database in sync.

Configuring Webhooks

1. Go to Dashboard > Webhooks.
2. Click Create Webhook.
3. Enter your endpoint URL (e.g., https://api.myapp.com/webhooks/email-validated).
4. Select the events you want to subscribe to (e.g., LIKELY, INVALID, DISPOSABLE).

Payload

We send a POST request to your URL with the following JSON body:

{
  "event": "validation.completed",
  "system": "CheckEmail.dev",
  "timestamp": "2025-12-21T10:00:00.000Z",
  "data": {
    "email": "[email protected]",
    "status": "LIKELY",
    "result": { ... }, // Full validation object
    "source": "api_async",
    "job_id": "123"
  }
}

Security

We include a signature in the X-CheckEmail-Signature header. This is an HMAC-SHA256 hash of the request body, signed with your webhook secret (visible in the dashboard).

To verify the webhook:

const crypto = require('crypto');

const signature = req.headers['x-checkemail-signature'];
const secret = 'whsec_...'; // Your secret
const payload = JSON.stringify(req.body);

const expected = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature === expected) {
  // Verified
}