> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks KYB : événements, payloads et signature

> Webhooks KYB Didit : événements de session et entités Business, payloads et signature HMAC. Dès $2.00 par vérification, sans engagement.

Les webhooks KYB de Didit informent votre backend lorsqu'une session de Vérification d'entreprise (KYB) change de statut, ou lorsqu'un réviseur ou le registre modifie ses données.
Les entités d'entreprise ont leurs propres événements.
Abonnez-vous aux événements qui vous intéressent via l'[API des destinations de webhook](https://docs.didit.me/fr/management-api/webhook/list-destinations.md) ou la Business Console.

## Catalogue des événements

Les événements de session sont communs aux sessions utilisateur et entreprise.
Le champ `session_kind` du payload indique à quel type de session l'événement se rapporte.
Les événements au niveau de l'entité sont distincts des événements au niveau de la session.

### Événements au niveau de la session

| Événement | Déclenchement |
| - | - |
| `status.updated` | Le statut d'une session a changé. Pour les sessions de Vérification d'entreprise (KYB), le payload contient `session_kind: "business"`. C'est l'événement à suivre pour connaître la progression. |
| `data.updated` | Un réviseur a modifié les données du registre, a ignoré ou régénéré les personnes clés dans la console, ou le registre a signalé un changement (lorsque la [surveillance du registre](https://docs.didit.me/fr/getting-started/kyb-registry-pricing.md) est disponible). Le champ `trigger` indique lequel. |

`data.updated` n'est pas envoyé lorsque le demandeur téléverse un document ou soumet les personnes clés, ni lorsqu'une nouvelle analyse AML se termine.
Utilisez `status.updated` ou [récupérez la décision de la session](https://docs.didit.me/fr/sessions-api/retrieve-session.md) pour suivre cette progression.

### Événements de l'entité d'entreprise

| Événement | Déclenchement |
| - | - |
| `business.status.updated` | Le statut de l'[entité d'entreprise](https://docs.didit.me/fr/entities/businesses/overview.md) liée a changé (`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated` | Les champs de profil ou les compteurs agrégés de l'entité d'entreprise ont changé. |

Abonnez votre destination de webhook à la combinaison d'événements de votre choix.
Consultez les [webhooks d'entité](https://docs.didit.me/fr/entities/webhooks.md) pour la référence complète des événements des entités d'entreprise et utilisateur.

## Structure du payload

Les webhooks de session utilisent un payload plat, sans enveloppe `data`.
L'enveloppe, les en-têtes de signature et tous les champs communs sont documentés dans la [référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md#structure-du-payload).
Une session KYB ajoute les champs suivants :

| Champ | Type | Description |
| - | - | - |
| `session_kind` | `"business"` | Permet à un gestionnaire générique de distinguer KYC et KYB. |
| `business_session_id` | `uuid` | Égal à `session_id`. |
| `vendor_business_id` | chaîne | Votre identifiant de l'entité d'entreprise, lorsqu'il est fourni à la création de la session. |
| `status` | chaîne | Le libellé exact, par exemple `"In Progress"`, `"Approved"` ou `"Awaiting User"`. Voir les [statuts](https://docs.didit.me/fr/business-verification/statuses.md). |
| `trigger` | chaîne | Facultatif. Raison de l'envoi du webhook. Pour `data.updated` en KYB : `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` ou `"kyb_registry_change"`. |
| `decision` | objet | Présent lorsque `status` vaut `Approved`, `Declined`, `In Review` ou `Abandoned`. Même structure que [`GET /v3/session/{id}/decision/`](https://docs.didit.me/fr/sessions-api/retrieve-session), voir le [schéma de réponse](https://docs.didit.me/fr/business-verification/response-schema.md). |
| `resubmit_info` | objet | Présent lorsque `status` vaut `Resubmitted`. |

### `status.updated` pour une session KYB

```json theme={null}
{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}
```

Le bloc `decision` contient `registry_checks[]`, `key_people_checks[]`, `document_verifications[]`, `aml_screenings[]` ainsi que les autres tableaux KYB.

### `data.updated` pour une session KYB

`data.updated` contient la même enveloppe plate que `status.updated`, avec en plus un `trigger` qui indique la raison de l'envoi.
Lorsque le statut de la session vaut `Approved`, `Declined`, `In Review` ou `Abandoned`, il contient aussi la `decision` actuelle.
Récupérez de nouveau la décision pour voir ce qui a changé.
Le payload ne contient pas de liste `changed_fields`.

### `business.status.updated` et `business.data.updated`

Les événements d'entité sont également plats.
Ils contiennent `vendor_business_id`, `vendor_data`, `status` (`ACTIVE`, `FLAGGED` ou `BLOCKED`) et `created_at`.
`business.status.updated` ajoute `previous_status`.
`business.data.updated` ajoute `changed_fields` ainsi qu'une map `changes` de la forme `{ field: { previous, current } }`.

```json theme={null}
{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}
```

## Vérification de signature

Chaque webhook est signé avec HMAC-SHA256 à l'aide du secret partagé de votre destination.
Vérifiez le corps brut de la requête avec l'en-tête `X-Signature-V2` (recommandé) et rejetez les envois dont l'en-tête `X-Timestamp` date de plus de 300 secondes.
La [référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md#vérification-de-la-signature) répertorie tous les en-têtes de signature, le chevauchement lors de la rotation du secret de signature, ainsi que des exemples de code.

## Politique de nouvelle tentative

* Une réponse `5xx` ou `404`, un délai d'attente ou un échec de connexion déclenche jusqu'à 2 nouvelles tentatives, après environ 1 minute puis environ 4 minutes, après quoi l'envoi est abandonné.
* Les autres réponses `4xx` et `3xx` ne sont pas réessayées.
* Chaque nouvelle tentative conserve le même `event_id` : dédupliquez sur ce champ.
* Vous pouvez renvoyer un envoi depuis le journal de livraison de la destination. La [référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md#politique-de-nouvelles-tentatives) détaille la politique complète.

## Abonnement

Abonnez-vous aux événements qui vous intéressent sur une [destination de webhook](https://docs.didit.me/fr/management-api/webhook/create-destination.md) :

```bash theme={null}
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'
```

Pour filtrer les sessions entreprise de votre côté, vérifiez `session_kind === "business"` dans les événements `status.updated` et `data.updated`.

## Étapes suivantes

> [card] [Référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md)
>
> Destinations, signature, nouvelles tentatives, schémas courants.

> [card] [Statuts](https://docs.didit.me/fr/business-verification/statuses.md)
>
> Référence des statuts de session et de fonctionnalité.

> [card] [Schéma de réponse](https://docs.didit.me/fr/business-verification/response-schema.md)
>
> Décodage du payload de décision KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.