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": [...]
}

​
Verifying Webhook Authenticity

Every webhook we send is signed so you can confirm it genuinely comes from FullEnrich and wasn’t tampered with in transit. We include an X-Signature-SHA1 header on each request — an HMAC-SHA1 signature of the request body, using your FullEnrich API key as the secret. To verify a webhook:
  1. Get the signature — read the X-Signature-SHA1 value from the request headers.
  2. Read the raw body — use the raw request body bytes exactly as received (UTF-8). Don’t re-serialize the parsed JSON, as key ordering or whitespace changes will break the check.
  3. Compute the HMAC — create an HMAC-SHA1 hash of the body using your API key as the secret, and hex-encode the result (lowercase).
  4. Compare — if your computed hash matches the X-Signature-SHA1 header, the request is authentic. Use a constant-time comparison to avoid timing attacks.
Verify the signature against the raw request body, before any JSON parsing or reformatting. Signing a re-serialized payload will produce a different hash and fail the check.
import crypto from "crypto";

// Use the raw request body (e.g. via express.raw({ type: "application/json" }))
function isValidWebhook(rawBody, signatureHeader, apiKey) {
  const expected = crypto
    .createHmac("sha1", apiKey)
    .update(rawBody, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.header("X-Signature-SHA1");

  if (!isValidWebhook(req.body, signature, process.env.FULLENRICH_API_KEY)) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(req.body);
  // ... handle the verified payload
  res.sendStatus(200);
});

​
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.

​
Real-Time Webhook Events

​
webhook_events.contact_finished

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.

​
Event Payload

The webhook receives the enriched profile immediately after processing. The payload follows the standard response format with a single contact in the data array: 
{
  "id": "<string>",
  "name": "<string>",
  "status": "IN_PROGRESS",
  "cost": {
    "credits": 10
  },
  "data": [
    {
      "input": {
        "first_name": "<string>",
        "last_name": "<string>",
        "full_name": "<string>",
        "company_domain": "<string>",
        "company_name": "<string>",
        "professional_network_url": "<string>"
      },
      "custom": {},
      "contact_info": {
        "most_probable_work_email": {
          "email": "<string>",
          "status": "DELIVERABLE"
        },
        "most_probable_personal_email": {
          "email": "<string>",
          "status": "DELIVERABLE"
        },
        "most_probable_phone": {
          "number": "<string>",
          "region": "<string>"
        },
        "work_emails": [
          {
            "email": "<string>",
            "status": "DELIVERABLE"
          }
        ],
        "personal_emails": [
          {
            "email": "<string>",
            "status": "DELIVERABLE"
          }
        ],
        "phones": [
          {
            "number": "<string>",
            "region": "<string>"
          }
        ]
      },
      "profile": {
        "id": "<string>",
        "full_name": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "location": {
          "country": "<string>",
          "country_code": "<string>",
          "city": "<string>",
          "region": "<string>"
        },
        "social_profiles": { ... },
        "educations": [{ ... }],
        "languages": [{ ... }],
        "skills": ["<string>"],
        "employment": { ... }
      }
    }
  ]
}
The status will be IN_PROGRESS since individual contacts are sent as they complete, before the entire batch finishes.