Skip to main content
If you’re using Zapier, Make, Clay, or n8n, webhooks are handled automatically by these platforms. You can skip this section.
The Enrich API and Reverse Email Lookup are asynchronous. This means when you start an operation, the API returns immediately with an ID, and results are delivered later via webhook. Async Schema

​
Why Webhooks?

Webhooks are notifications sent directly to your server when results are ready. Instead of you having to check for results, we push them to you immediately. Benefits:
  • Fastest method to receive results
  • No need to keep a connection open
  • No HTTP timeouts or retries to manage
  • Simpler and more reliable than polling

​
How It Works

  1. When you start an enrichment or reverse lookup, include a webhook_url in your request
  2. We process your contacts (typically 30-90 seconds per contact)
  3. When done, we POST the results directly to your webhook URL
The content sent to your webhook is the same as what you’d get from the GET endpoint.

​
Webhook Parameters

​
webhook_url — Batch Completion

Your webhook URL receives a POST request when the entire batch is finished, lacks credits, or is canceled. 
{
  "name": "My Enrichment",
  "webhook_url": "https://your-server.com/webhook",
  "data": [...]
}

​
webhook_events.contact_finished — Real-Time Per-Contact

If you need results as fast as possible, use this parameter. It fires a webhook immediately after each individual contact is enriched, without waiting for the entire batch to complete. This is perfect for real-time integrations where you want to process results as they come in. 
{
  "name": "My Enrichment",
  "webhook_url": "https://your-server.com/webhook/batch-complete",
  "webhook_events": {
    "contact_finished": "https://your-server.com/webhook/single-contact"
  },
  "data": [...]
}
You can use both webhook_url and webhook_events.contact_finished together. You’ll receive a webhook for each contact as it completes, plus a final webhook when the entire batch is done.

​
Reliability & Retries

Webhooks are reliable by design. If we can’t deliver your result (for example, receiving a non-2xx status code), we’ll automatically retry every minute, up to 5 times. For most use cases, you can treat webhooks as “guaranteed delivery.” If there’s ever a question about a specific result or missed event, our team can check our delivery logs on request.

​
Tracking Requests with custom

You can easily keep track of which result belongs to which user or request by using the custom parameter. Include any identifier you need (User ID, CRM contact ID, etc.), and it will be returned exactly as provided in the webhook payload. 
{
  "data": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "domain": "example.com",
      "custom": {
        "user_id": "12584",
        "crm_contact_id": "abc-123"
      }
    }
  ]
}
Custom field values must be strings. Numbers will return an error.

​
Testing Webhooks

A quick way to test webhooks and see the payload structure is to use webhook.site — a free service that gives you a temporary URL to receive and inspect webhook requests.
Polling means repeatedly calling the GET endpoint to check if the operation is finished. This is not recommended because:
  • It consumes your rate limit quota
  • Results come slower than with webhooks
  • More complex to implement reliably
If you must use polling, don’t poll more than once every 5-10 minutes. Never poll every few seconds.