## Qu'est-ce qu'un webhook ?

Un webhook est une URL de votre côté que Dropcontact appelle quand vos résultats sont prêts. Au lieu de demander plusieurs fois à l'API si vos données sont prêtes, vous nous donnez une URL et nous y envoyons les résultats dès que l'enrichissement est terminé.

Il y a deux façons de recevoir des webhooks :

1. La façon recommandée : avec une custom callback URL.
2. Avec une URL de webhook par défaut.

Vous ne pouvez avoir qu'une seule URL de webhook par défaut par compte. Si une `custom_callback_url` est indiquée dans la requête POST, elle est prioritaire sur l'URL par défaut.

Votre URL peut commencer par `http://` ou `https://`.

## Custom callback URL

Ajoutez le champ `custom_callback_url` dans le corps de votre requête [Enrichir un lot de contacts](https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/). Une fois l'enrichissement terminé, les résultats sont envoyés à cette URL. C'est la façon la plus simple d'utiliser les webhooks, sans aucune configuration préalable.

**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,
        "custom_callback_url": "https://votre-domaine.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: VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{"data": [{"first_name": "Denis", "last_name": "Cohen", "website": "dropcontact.com", "email": "dc@dropcontact.io"}], "siren": true, "custom_callback_url": "https://votre-domaine.com/callback"}'
```

## URL de webhook par défaut

Vous pouvez, si vous le souhaitez, définir une URL de webhook par défaut, utilisée pour toutes vos requêtes d'enrichissement qui n'indiquent pas de `custom_callback_url`.

Gérez-la avec les endpoints dédiés :

- La définir ou la modifier : [Définir l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/set-the-default-webhook-callback-url/)
- Voir sa valeur actuelle : [Consulter l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/get-the-default-webhook-callback-url/)
- La supprimer : [Supprimer l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/delete-the-default-webhook-callback-url/)

Après suppression, seules les requêtes avec une `custom_callback_url` déclenchent des webhooks.

## Recevoir un webhook

Dropcontact envoie une requête `POST` à votre URL une fois tous les contacts de la requête traités, même si vous avez déjà récupéré une partie des résultats avec `forceResults`. Son corps est une liste de webhooks au format JSON. Chaque webhook contient les champs suivants :

| Champ | Type | Description |
| --- | --- | --- |
| `id` | string | Identifiant unique du webhook. |
| `version` | integer | Version du format du webhook. Actuellement `1`. |
| `event_type` | string | Type d'événement. Toujours `enrich_api_result` pour les résultats d'enrichissement. |
| `occurred_at` | integer | Date de l'événement, en secondes depuis le 1er janvier 1970 (timestamp Unix). |
| `data` | object | Les résultats : `request_id` (l'ID de requête retourné par votre requête POST) et `data` (les contacts enrichis, au même format que [Récupérer les résultats d'enrichissement](https://developer.dropcontact.com/fr/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"
            }]
        }
    }
]
```

> **Remarque:** Le champ `data` ne contient pas le champ `credits_left`. Utilisez l'endpoint [Consulter les crédits](https://developer.dropcontact.com/fr/reference/get-credits/) pour l'obtenir.

> **Remarque:** Une requête est toujours envoyée depuis l'une de ces adresses IP : `18.202.84.106`, `52.48.65.147` ou `54.74.141.102`.

> **Attention:** Nous ne garantissons pas l'ordre des webhooks. Utilisez le `request_id` pour associer chaque webhook à la requête correspondante. De plus, dans de rares cas, vous pouvez recevoir le même `request_id` dans plusieurs webhooks.

## Répondre à un webhook

Votre serveur doit répondre avec un code HTTP inférieur à `400` (par exemple `200`) en moins de 5 secondes. Un code de `400` ou plus, une absence de réponse en 5 secondes ou une erreur de connexion compte comme un échec.

En cas d'échec, nous réessayons :

1. D'abord, jusqu'à 4 essais en quelques secondes.
2. Ensuite, jusqu'à 10 nouveaux essais plus tard, en attendant un peu plus à chaque fois : 16 secondes, puis 32 secondes, et ainsi de suite, jusqu'à environ 2 heures 15 entre deux essais.

Après ces 14 essais, le webhook est abandonné. Vous pouvez toujours récupérer les résultats avec [Récupérer les résultats d'enrichissement](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/).

À cause de ces nouveaux essais, vous pouvez recevoir le même webhook plusieurs fois. Utilisez le `request_id` pour ignorer ceux que vous avez déjà traités.