Skip to main content

​
Why use webhooks?

Webhooks let results come to you instead of you repeatedly asking for them. Rather than polling a GET endpoint until a search finishes, Enrow sends each result to your server the moment it’s ready — saving requests, reducing latency, and keeping your code simple. Stop wasting requests — let results come to you. Because every Enrow endpoint is asynchronous, webhooks are the recommended way to receive results across Email Finder, Email Verifier, and Phone Finder. Webhooks also bypass rate limits entirely, since Enrow calls you rather than the other way around.

​
How does a webhook flow work?

A webhook flow turns a single search request into an automatic delivery. You tell Enrow where to send results, and Enrow does the rest:
  1. You POST a search request with a webhook URL in the settings
  2. Enrow returns a search ID immediately
  3. Enrow processes the search in the background
  4. When complete, Enrow POSTs results to your webhook URL

​
How do I set up a webhook?

You can register a webhook in two ways, depending on whether you want it for one search or every search:
  1. Per-request: Include a webhook URL in the settings object of any API call
  2. Global: Configure a default webhook from the integrations page on the dashboard
{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "settings": {
    "webhook": "https://your-app.com/webhooks/enrow"
  }
}
Your webhook URL must be a valid HTTPS endpoint that returns a 200 status code.

​
Which events trigger a webhook call?

Six types of events can trigger a webhook call, one per endpoint and search type:
EventDescription
single_search_finishedA single email search has finished
bulk_search_finishedA bulk email search has finished
verification_finishedA single email verification has finished
bulk_verification_finishedA bulk email verification has finished
single_phone_search_finishedA single phone search has finished
bulk_phone_search_finishedA bulk phone search has finished

​
What does a webhook payload look like?

The webhook payload depends on the endpoint and whether the search was single or bulk. Single searches deliver the full result directly, while bulk searches deliver a completion notification that you follow up with a GET request.

​
Email Finder — Single

For single searches, you receive the full result directly in the webhook notification. This removes the need to perform a GET request. 
{
  "event": "single_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 1
  },
  "result": {
    "email": "dwight.schrute@dundermifflin.com",
    "qualification": "valid",
    "custom": "your_custom_data",
    "info": {
      "company_domain": "dundermifflin.com",
      "fullname": "Dwight Schrute",
      "firstname": "Dwight",
      "lastname": "Schrute"
    }
  }
}

​
Email Finder — Bulk

For bulk searches, you receive a notification that the batch is finished. Then call the GET /email/find/bulk endpoint with the id to retrieve results. 
{
  "event": "bulk_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 2284
  }
}

​
Email Verifier — Single

The full result is included directly — no GET request needed. 
{
  "event": "verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "email": "pam.beesly@dundermifflin.com",
  "qualification": "valid",
  "custom": "your_custom_data"
}

​
Email Verifier — Bulk

This is a notification only. Call GET /email/verify/bulk with the id to retrieve results. 
{
  "event": "bulk_verification_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 386.25
  }
}

​
Phone Finder — Single

The full result is included directly — no GET request needed. 
{
  "event": "single_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt",
  "credits": {
    "cost": 50
  },
  "result": {
    "number": "+15705551234",
    "params": {
      "linkedin_url": "https://www.linkedin.com/in/michael-scott"
    },
    "qualification": "found"
  }
}

​
Phone Finder — Bulk

This is a notification only. Call GET /phone/bulk with the id to retrieve results. 
{
  "event": "bulk_phone_search_finished",
  "id": "910f3e13-b2bf-442d-ab0b-4cf44dfrij84fjrt"
}

​
How are single and bulk webhooks different?

Single-search webhooks contain the complete result, so no extra call is needed. Bulk-search webhooks only signal that the batch is done — you then fetch the results with the matching GET endpoint.
TypeSingle searchesBulk searches
PayloadFull result includedNotification only (ID + credits)
GET needed?NoYes — use the GET endpoint with the id
For single searches, the webhook contains everything you need. For bulk searches, the webhook tells you the batch is done — then you fetch the results.

​
What are the best practices for webhook endpoints?

A reliable webhook endpoint returns quickly, accepts only HTTPS, and tolerates the occasional duplicate. Follow these practices to keep deliveries dependable:
Process webhook payloads asynchronously. Return a 200 immediately, then handle the data in a background job.
Always use HTTPS endpoints. HTTP webhooks will be rejected.
In rare cases, webhooks may be delivered more than once. Use the id field to deduplicate.
Pass custom data in your requests to identify which record a webhook result belongs to:
{
  "fullname": "Dwight Schrute",
  "company_domain": "dundermifflin.com",
  "custom": { "crm_id": "lead_001" }
}
The custom field is returned as-is in the webhook payload.

​
Should I use webhooks or polling?

Use webhooks for production and polling only for quick prototyping or debugging. Webhooks deliver results in real time without consuming your request quota, while polling makes repeated GET calls that count against your rate limits.
WebhooksPolling (GET)
LatencyReal-timeDepends on poll interval
API calls0 (Enrow calls you)Multiple calls per search
Rate limit impactNoneConsumes quota
ComplexityRequires endpoint setupSimpler to implement
We recommend webhooks for production use. Use polling only for quick prototyping or debugging.

​
FAQ

No. Webhooks don’t consume additional credits — you only pay for the search itself. The credit cost is reported in the credits.cost field of the payload. See Credits & billing for per-endpoint costs.
Your webhook URL must be a valid HTTPS endpoint that returns a 200 status code. If your server is unreachable or responds with another status, the delivery is treated as failed. As a fallback, you can always retrieve results by polling the relevant GET endpoint with the search id.
Use the id from the search response, or pass a custom object in your request — it’s returned as-is in the webhook payload so you can map results back to your own records, such as a CRM lead ID.
The most common causes are a non-HTTPS URL, an endpoint that doesn’t return 200, or a server that times out. Confirm your endpoint is publicly reachable over HTTPS. For broader troubleshooting, see Error handling and Status codes.

​
Next steps

Find an email

Pass a webhook URL in settings to get the result delivered automatically.

Get bulk results

Fetch batch results after a bulk_search_finished webhook fires.

Authentication

How to pass your API key in the x-api-key header.

Rate limits

See why webhooks avoid the request quota that polling consumes.