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:- You POST a search request with a
webhookURL in thesettings - Enrow returns a search ID immediately
- Enrow processes the search in the background
- 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:- Per-request: Include a
webhookURL in thesettingsobject of any API call - Global: Set a default webhook on the API page of the dashboard. Enrow checks the URL when you save it: see How do I verify my webhook endpoint?
webhook, what happens to the default one depends on the endpoint:
- Email Finder: Enrow notifies both URLs (once if they are the same)
- Phone Finder and Email Verifier: the per-request URL replaces the default one
How do I verify my webhook endpoint?
When you save a new default webhook URL on the API page, Enrow first sends it a one-time verification request to confirm that you control the endpoint. The URL is saved only if your endpoint answers it correctly. Enrow sends aPOST request with this JSON body:
2xx status code and send back the same challenge value, either as the raw response body or as JSON:
2xx, a challenge that doesn’t match, an unreachable URL, or a private or internal address) and your current webhook stays active. A webhook passed in the settings of a request is not checked this way.
Which events trigger a webhook call?
Six types of events can trigger a webhook call, one per endpoint and search type: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.Search from a LinkedIn profile URL
For a search launched from a LinkedIn profile URL,result also carries linkedin_status and linkedin_url (the URL you sent). info is only included when an email is found: a search that finds nothing never names the person. credits.cost is the final cost, like credits_used in the GET response, which also explains each linkedin_status.
Email Finder — Bulk
For bulk searches, you receive a notification that the batch is finished. Then call the GET /email/find/bulk endpoint with theid to retrieve results.
Email Verifier — Single
The full result is included directly — no GET request needed.Email Verifier — Bulk
This is a notification only. Call GET /email/verify/bulk with theid to retrieve results.
Phone Finder — Single
The full result is included directly — no GET request needed.Phone Finder — Bulk
This is a notification only. Call GET /phone/bulk with theid to retrieve results.
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.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, uses HTTPS, and tolerates the occasional duplicate. Follow these practices to keep deliveries dependable:Return 200 Quickly
Return 200 Quickly
Process webhook payloads asynchronously. Return a
200 immediately, then handle the data in a background job.Use HTTPS
Use HTTPS
Use an HTTPS endpoint so results travel encrypted. Plain HTTP URLs are accepted, but not recommended.
Handle Duplicates
Handle Duplicates
In rare cases, webhooks may be delivered more than once. Use the
id field to deduplicate.Use Custom Fields
Use Custom Fields
Pass The
custom data in your requests to identify which record a webhook result belongs to: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.We recommend webhooks for production use. Use polling only for quick prototyping or debugging.
FAQ
Do webhooks cost extra credits?
Do webhooks cost extra credits?
No. Webhooks don’t consume additional credits: you only pay for the search itself. Email Finder and Email Verifier payloads report the credit cost in the
credits.cost field. It is the final cost once refunds are applied: 0 for a single search that found nothing (0.25 for an email search from a LinkedIn profile URL or for an account whose success rate is abnormally low), and for a bulk, the rows found plus any charged misses. Phone Finder payloads don’t include the cost. See Credits & billing for per-endpoint costs.What happens if my endpoint doesn't return a 200?
What happens if my endpoint doesn't return a 200?
Enrow sends each notification once. If your server is unreachable or responds with a status other than
2xx, the delivery fails and is not retried. You can always retrieve the results by polling the relevant GET endpoint with the search id.How do I match a webhook to the original request?
How do I match a webhook to the original request?
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.Why didn't I receive a webhook?
Why didn't I receive a webhook?
The most common causes are an endpoint that doesn’t return
2xx, a server that times out, or a URL that isn’t publicly reachable. Failed deliveries are not retried: fetch the result with the matching GET endpoint and the search id. 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.

