> ## 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 d'entités : événements utilisateur et entreprise

> Webhooks Didit en temps réel pour les entités Utilisateur et Entreprise : changements de statut, profil, signature et relances.



Prompt des webhooks d'entité
        Copier le prompt dans le presse-papiers



      
      

\<pre>

\````# Goal — subscribe to entity-level webhooks and apply changes to my database

Entity webhooks fire whenever a User or Business entity changes its status or its profile data. Use them to keep your local mirror of Didit entities in sync.

\## Entity-level event catalog

\| `webhook_type` | Trigger |
\|---|---|
\| `user.status.updated` | User entity status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`). Payload includes `previous_status`. |
\| `user.data.updated` | User entity profile / counters / metadata changed. Includes `changed_fields` and a `changes` map of `{previous, current}`. |
\| `business.status.updated` | Business entity status changed. Payload includes `previous_status`. |
\| `business.data.updated` | Business entity profile or aggregates changed. Includes `changed_fields` and `changes`. |

\`activity.created` is accepted in `subscribed_events` and by the Try Webhook tester, but Didit does not deliver it for live traffic. Do not build on it.

Session-level events (`status.updated`, `data.updated`) and transaction events (`transaction.created`, `transaction.status.updated`) live alongside but are separate — see /integration/webhooks for the full catalog.

\## Register a destination

\```bash
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Entity sync",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": [
  "user.status.updated",
  "user.data.updated",
  "business.status.updated",
  "business.data.updated"
]
}'
\```

Persist the returned destination `secret_shared_key` — that's the HMAC signing key.

\## Payload shape

Entity payloads are flat: there is no `data` wrapper and no `event` key. Read `webhook_type`.

\```json
\{
"event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
"webhook_type": "user.status.updated",
"timestamp": 1776333600,
"created_at": 1776333594,
"application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"environment": "live",
"vendor_user_id": "9c7d2a30-...",
"vendor_data": "user-42",
"status": "BLOCKED",
"previous_status": "ACTIVE"
}
\```

\`business.*` events use `vendor_business_id` instead of `vendor_user_id`.
\`user.data.updated` / `business.data.updated` payloads keep `status` and add `changed_fields` (array) and `changes` (`{field: {previous, current}}`). Use these to apply minimal diffs to your DB.

\## Verify the signature

Verify X-Signature-V2 (recommended): HMAC-SHA256 of the canonical JSON body with the destination `secret_shared_key`, then a constant-time compare, and reject an X-Timestamp older than 300 seconds. See /integration/webhooks for the signature headers and code samples. Respond `2xx` within **5 seconds**. On a 5xx, 404, timeout or connection failure Didit retries up to 2 times (about 1 minute, then about 4 minutes later); see /integration/webhooks#retry-policy.

\## Idempotency

Every delivery carries a unique `event_id`. De-dupe on it. Fallback compound key: `(application_id, webhook_type, vendor_data, timestamp)`.

\## Failure modes

\- Wrong `webhook_version` (e.g. v2) → singular fields and older event names; v3 is required for entity events plural-array contract.
\- Slow handler → retried; budget < 5s; do heavy work async.
\- Unknown event type → log and 200; new event types may be added.

\## Apply-decision pseudocode

\```ts
switch (event.webhook_type) {
case "user.status.updated":
await db.users.update({ vendor_data: event.vendor_data }, { status: event.status });
break;
case "user.data.updated":
for (const field of event.changed_fields) {
  await db.users.update({ vendor_data: event.vendor_data }, { [field]: event.changes[field].current });
}
break;
case "business.status.updated":
case "business.data.updated": /* same shape, businesses table, keyed by vendor_business_id */ break;
}
\```

\## Sources of truth

\- /integration/webhooks — destinations, signatures, retries, full event catalog
\- /management-api/webhook/create-destination — endpoint schema
\- /entities/users/operations — operations that emit user events
\- /entities/businesses/operations — operations that emit business events
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Coller dans

Chaque modification du statut ou des données de profil d'une entité User ou Business émet un webhook, afin que votre système puisse réagir en temps réel.
Utilisez les webhooks d'entité pour synchroniser les données de profil, propager les blocages vers d'autres systèmes ou déclencher des flux de conformité en aval.## Catalogue des événements| Événement | Déclencheur |
| - | - |
| `user.status.updated` | Le statut d'une entité User change (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`) |
| `user.data.updated` | Les champs de profil d'une entité User changent (nom, date de naissance, portrait, compteurs agrégés, métadonnées) |
| `business.status.updated` | Le statut d'une entité Business change |
| `business.data.updated` | Les champs de profil d'une entité Business changent (raison sociale, numéro d'immatriculation, pays, compteurs) |> [!NOTE]
>
> `activity.created` est accepté dans `subscribed_events` et couvert par le testeur **Try Webhook**, mais Didit ne le livre pas actuellement pour le trafic en production.
> Ne construisez pas de réplication de la chronologie à partir de cet événement.Didit émet aussi des événements de session, de transaction et de session entreprise qui référencent des champs d'entité. Voir :- [Webhooks KYB](https://docs.didit.me/fr/business-verification/webhooks.md) : événements de session d'entreprise
- [Webhooks de surveillance des transactions](https://docs.didit.me/fr/transaction-monitoring/webhooks.md) : événements de transaction
- [Référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md) : vérification de signature, réessais, destinations## Structure des payloadsLes payloads des webhooks d'entité sont à plat : il n'y a ni wrapper `data` ni clé `event`.
Lisez `webhook_type` pour router l'événement.```json theme={null}
{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "user.status.updated",
  "timestamp": 1776333600,
  "created_at": 1776333594,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}
```| Champ | Description |
| - | - |
| `vendor_user_id` / `vendor_business_id` | Identifiant Didit de l'entité. Les événements `business.*` utilisent `vendor_business_id`. |
| `vendor_data` | Votre identifiant pour l'entité. |
| `status` | `ACTIVE`, `FLAGGED` ou `BLOCKED`. |
| `previous_status` | Uniquement sur `*.status.updated`. |
| `changed_fields` et `changes` | Uniquement sur `*.data.updated`. |
| `created_at` | Secondes Unix de la dernière mise à jour de l'entité. |
| `timestamp` | Secondes Unix auxquelles Didit a envoyé le webhook. |### `user.status.updated` / `business.status.updated`Déclenché à chaque changement de statut.
Le payload contient `status` et `previous_status`.
Il n'indique pas la raison du changement de statut : ouvrez l'entité dans la console si vous avez besoin de la cause.### `user.data.updated` / `business.data.updated`Déclenché lorsque des champs de profil changent.
`changed_fields` liste les champs modifiés et `changes` contient les valeurs `previous` et `current` de chacun.```json theme={null}
{
  "event_id": "5d1e8f9a-0c32-4b6a-a7b6-2b9d6f0a3c41",
  "webhook_type": "user.data.updated",
  "timestamp": 1776333700,
  "created_at": 1776333694,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_user_id": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "vendor_data": "user-42",
  "status": "ACTIVE",
  "changed_fields": ["full_name", "session_count"],
  "changes": {
    "full_name": { "previous": null, "current": "John Doe" },
    "session_count": { "previous": 2, "current": 3 }
  }
}
```Les champs susceptibles d'apparaître dans `changed_fields` sont :- User : `vendor_data`, `display_name`, `full_name`, `date_of_birth`, `metadata`, `portrait_image`, `issuing_states`, `approved_emails`, `approved_phones`, `features`, `session_count`, `approved_count`, `declined_count`, `in_review_count`, `first_session_at`, `last_session_at`.
- Business : `vendor_data`, `display_name`, `metadata`, `legal_name`, `registration_number`, `country_code`, `session_count`, `approved_count`, `declined_count`, `in_review_count`, `features`, `first_session_at`, `last_session_at`.Utilisez `changed_fields` et `changes` pour ne synchroniser que les champs modifiés.## Livraison, réessais et signatureTous les webhooks d'entité suivent le contrat de livraison standard :- **Signé** avec HMAC-SHA256 dans l'en-tête `X-Signature-V2` (recommandé), avec le `secret_shared_key` de la destination. `X-Signature` et l'ancien `X-Signature-Simple`, obsolète, sont également envoyés, ainsi que `X-Timestamp`.
- **Réessayé** jusqu'à 2 fois, après environ 1 minute puis environ 4 minutes, lorsque votre endpoint répond 5xx ou 404, dépasse le délai d'attente ou ne parvient pas à établir la connexion. La [référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md#politique-de-nouvelles-tentatives) détaille la politique complète.
- **Idempotence** : chaque webhook possède un `event_id` unique dans le payload ; dédoublonnez de votre côté.Voir [Référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md) pour la configuration de la destination et des exemples de code de vérification de signature.## AbonnementAbonnez-vous aux événements d'entité sur une destination de webhook via l'API de gestion ou la Business Console :```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": "Entity sync",
    "url": "https://yourapp.com/webhooks/didit",
    "subscribed_events": [
      "user.status.updated",
      "user.data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'
```## Étapes suivantes> [card] [Référence des webhooks](https://docs.didit.me/fr/integration/webhooks.md)
>
> Destinations, signatures, réessais et vérification.> [card] [Créer une destination](https://docs.didit.me/fr/management-api/webhook/create-destination.md)
>
> Enregistrez un nouvel endpoint de webhook.> [card] [Opérations sur les utilisateurs](https://docs.didit.me/fr/entities/users/operations.md)
>
> Modifications qui déclenchent les webhooks utilisateur.


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