Webhooks KYB : événements, payloads et signature

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 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 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 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 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é 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. 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.
`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/`, voir le schéma de réponse.
`resubmit_info`	objet	Présent lorsque `status` vaut `Resubmitted`.

`status.updated` pour une session KYB

{
  "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 } }.

{
  "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 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 détaille la politique complète.

Abonnement

Abonnez-vous aux événements qui vous intéressent sur une destination de webhook :

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

Référence des webhooks

Destinations, signature, nouvelles tentatives, schémas courants.

Statuts

Référence des statuts de session et de fonctionnalité.

Schéma de réponse

Décodage du payload de décision KYB.

Prise en main

Fonctionnalités

Profils d'entreprise

Référence

Console

Webhooks KYB : événements, payloads et signature

Catalogue des événements

Événements au niveau de la session

Événements de l’entité d’entreprise

Structure du payload

`status.updated` pour une session KYB

`data.updated` pour une session KYB

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

Vérification de signature

Politique de nouvelle tentative

Abonnement

Étapes suivantes

Référence des webhooks

Statuts

Schéma de réponse

​Catalogue des événements

​Événements au niveau de la session

​Événements de l’entité d’entreprise

​Structure du payload

​status.updated pour une session KYB

​data.updated pour une session KYB

​business.status.updated et business.data.updated

​Vérification de signature

​Politique de nouvelle tentative

​Abonnement

​Étapes suivantes

Référence des webhooks

Statuts

Schéma de réponse

Catalogue des événements

Événements au niveau de la session

Événements de l’entité d’entreprise

Structure du payload

`status.updated` pour une session KYB

`data.updated` pour une session KYB

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

Vérification de signature

Politique de nouvelle tentative

Abonnement

Étapes suivantes