Webhooks

What is a webhook?Copy Anchor Link

A webhook is a URL on your side that Dropcontact calls when your results are ready. Instead of checking with the API from time to time whether your data is ready, you give us a URL and we send the results to it as soon as the enrichment is done.

There are two ways to receive webhooks:

1. The recommended way: with a custom callback URL.
2. With a default webhook URL.

You can only have one default webhook URL per account. If a custom_callback_url is provided in the POST request, it takes precedence over the default URL.

Your URL can start with http:// or https://.

Custom callback URLCopy Anchor Link

Add the custom_callback_url field to your Enrich a batch of records request body. When the enrichment is complete, the results are sent to this URL. This is the easiest way to use webhooks and requires no prior setup.

import requests

r = requests.post(
    "https://api.dropcontact.com/v1/enrich/all",
    json={
        "data": [
            {
                "first_name": "Denis",
                "last_name": "Cohen",
                "website": "dropcontact.com",
                "email": "dc@dropcontact.io",
            }
        ],
        "siren": True,
        "language": "en",
        "custom_callback_url": "https://your-domain.com/callback",
    },
    headers={
        "Content-Type": "application/json",
        "X-Access-Token": apiKey,
    },
)

Default webhook URLCopy Anchor Link

You can optionally set a default webhook URL that is used for all your enrichment requests that don't include a custom_callback_url.

Manage it with the dedicated endpoints:

• Set or update it: Set the default webhook callback URL
• See its current value: Get the default webhook callback URL
• Delete it: Delete the default webhook callback URL

After deletion, only requests with a custom_callback_url trigger webhooks.

Receive a webhookCopy Anchor Link

Dropcontact sends a POST request to your URL once all the contacts of the request are processed, even if you already fetched part of the results with forceResults. Its body is a JSON list of webhooks. Each webhook contains the following fields:

[
    {
        "id": "<unique-webhook-id>",
        "version": 1,
        "event_type": "enrich_api_result",
        "occurred_at": 1623153600,
        "data": {
            "request_id": "<your-POST-request-id>",
            "data": [{
                "first_name": "Peter",
                "last_name": "Jackson"
            }]
        }
    }
]

Respond to a webhookCopy Anchor Link

Your server must answer with an HTTP code below 400 (for example 200) within 5 seconds. A code of 400 or more, no answer within 5 seconds or a connection error counts as a failure.

If it fails, we try again:

1. First, up to 4 tries within a few seconds.
2. Then, up to 10 later tries, waiting longer each time: 16 seconds, then 32 seconds, and so on, up to about 2 hours 15 minutes between two tries.

After these 14 tries, the webhook is dropped. You can still get the results with Fetch enrichment results.

Because of these new tries, you may receive the same webhook more than once. Use the request_id to ignore the ones you have already processed.