## What is a webhook?

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 URL

Add the `custom_callback_url` field to your [Enrich a batch of records](https://developer.dropcontact.com/en/reference/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.

**Python**

```python
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,
    },
)
```

**Shell**

```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
  -H "X-Access-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"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"}'
```

## Default webhook URL

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](https://developer.dropcontact.com/en/reference/set-the-default-webhook-callback-url/)
- See its current value: [Get the default webhook callback URL](https://developer.dropcontact.com/en/reference/get-the-default-webhook-callback-url/)
- Delete it: [Delete the default webhook callback URL](https://developer.dropcontact.com/en/reference/delete-the-default-webhook-callback-url/)

After deletion, only requests with a `custom_callback_url` trigger webhooks.

## Receive a webhook

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:

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique ID of the webhook. |
| `version` | integer | Version of the webhook format. Currently `1`. |
| `event_type` | string | Type of event. Always `enrich_api_result` for enrichment results. |
| `occurred_at` | integer | Date of the event, in seconds since January 1, 1970 (Unix timestamp). |
| `data` | object | The results: `request_id` (the request ID returned by your POST request) and `data` (the enriched records, in the same format as [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/)). |

```json
[
    {
        "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"
            }]
        }
    }
]
```

> **Note:** The `data` field does not contain the `credits_left` field. Use the [Get Credits](https://developer.dropcontact.com/en/reference/get-credits/) endpoint to retrieve it.

> **Note:** A request is always sent from one of these IP addresses: `18.202.84.106`, `52.48.65.147` or `54.74.141.102`.

> **Warning:** We don't guarantee the order of the webhooks. You must use the `request_id` to match the webhooks with the corresponding request. Furthermore, in rare scenarios, you may receive the same `request_id` in multiple webhooks.

## Respond to a webhook

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](https://developer.dropcontact.com/en/reference/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.