> ## 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. # Créer une destination webhook API > Créez une destination webhook Didit avec version, événements abonnés et secret de signature dédié. Gestion des webhooks par API, à l'appel. Créer une destination de webhook via l'API Copier le prompt dans le presse-papiers \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

Example call:
curl -X POST "https://verification.didit.me/v3/webhook/destinations/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Production session webhooks",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated"]
}'

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
Coller dans Les destinations de webhook vous permettent d'envoyer différents événements Didit vers différentes URL. Chaque destination possède son propre `secret_shared_key`, sa propre `webhook_version` et sa propre liste `subscribed_events`.## Comment fonctionne `subscribed_events``subscribed_events` est un tableau obligatoire de noms d'événements exacts. Didit n'envoie un webhook à cette destination que si le `webhook_type` du payload correspond à l'une des valeurs du tableau.- Incluez au moins un événement. - Utilisez uniquement les noms d'événements pris en charge ci-dessous. - Ajoutez chaque événement que vous souhaitez recevoir ; il n'existe pas de valeur joker comme `*` ou `all`. - Pour router différents domaines de produits vers différents systèmes, créez plusieurs destinations avec des listes `subscribed_events` différentes.## Catalogue des événements| Événement | À utiliser lorsque vous avez besoin de | | - | - | | `status.updated` | Suivre les changements de statut d'une session de Vérification des utilisateurs (KYC) ou de Vérification d'entreprise (KYB). Les payloads KYB incluent `session_kind: "business"` et `business_session_id`. | | `data.updated` | Recevoir les données de vérification d'une session lorsqu'elles sont corrigées ou mises à jour après sa création, par exemple lors de modifications effectuées par un réviseur sur les données KYC, de justificatif de domicile ou KYB. | | `user.status.updated` | Suivre le changement de statut d'une entité User, par exemple `ACTIVE`, `FLAGGED` ou `BLOCKED`. | | `user.data.updated` | Suivre les changements du profil, des compteurs, des métadonnées, des documents ou des champs de vérification agrégés d'une entité User. | | `business.status.updated` | Suivre le changement de statut d'une entité Business, par exemple après un examen manuel, des résultats KYB ou une action de liste de blocage. | | `business.data.updated` | Suivre les changements du profil, des compteurs, des métadonnées, des champs d'immatriculation ou des champs de vérification agrégés d'une entité Business. | | `activity.created` | Accepté dans `subscribed_events` et couvert par **Try Webhook**, mais Didit n'envoie actuellement pas cet événement pour le trafic de production. | | `transaction.created` | Une transaction est créée dans la Surveillance des transactions et son évaluation initiale des règles est terminée. | | `transaction.status.updated` | Une transaction change de statut après l'application des règles, l'examen par un analyste, la remédiation, les mises à jour des fournisseurs ou des actions via l'API ou la console ; cet événement est aussi envoyé une fois lorsqu'un filtrage crypto relancé en arrière-plan se termine. | | `travel_rule.status.updated` | Un échange [Travel Rule](https://docs.didit.me/fr/transaction-monitoring/travel-rule.md) change de statut. | | `workflow.compliance_changed` | Le statut de conformité d'un workflow publié change après une réévaluation. | | `transaction_rule_suggestions.created` | Une exécution de suggestions de règles propose de nouvelles modifications de règles. |Les familles d'événements Investigator (`investigator.*`) et Authentication (`auth.*`) sont également acceptées. Tous les événements et leurs payloads sont décrits dans [Webhooks](https://docs.didit.me/fr/integration/webhooks.md#types-d’événements).Ensembles d'abonnement courants :```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```Pour des exemples de payloads et du code de signature, consultez le [guide des webhooks](https://docs.didit.me/fr/integration/webhooks.md). ## OpenAPI ````yaml fr/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de vérification d'identité. Authentifiez-vous avec l'en-tête x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Créer une destination de webhook description: "Créez une destination de webhook. La réponse inclut le secret de signature HMAC `secret_shared_key` généré automatiquement (également consultable ultérieurement via `GET /v3/webhook/destinations/{destination_uuid}/`). Envoyez toujours `subscribed_events` avec au moins un événement (aucun caractère générique)\_: une liste explicitement vide est rejetée avec une erreur 400, et omettre ce champ crée une destination abonnée à rien, qui ne reçoit jamais de webhook. La paire `(application, url)` doit être unique parmi les destinations de l'application." operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nom lisible par l'humain affiché dans Console → Webhooks. Permet de distinguer les destinations lorsque vous en avez plusieurs (par ex. "Prod", "Staging mirror"). url: type: string format: uri description: >- URL HTTPS qui recevra les requêtes `POST`. Doit être unique parmi les destinations de l'application. Utilisez un endpoint stable et renforcé : Didit réessaie les livraisons ayant échoué selon un calendrier d'intervalles progressifs. maxLength: 2000 enabled: type: boolean default: true description: >- Lorsque la valeur est `false`, la destination est enregistrée mais Didit n'y enverra aucun webhook. Pratique pour les configurations de staging que vous souhaitez laisser en attente. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Version du schéma de payload que Didit enverra. `v3` est le format actuel/recommandé ; les versions antérieures sont conservées pour des raisons de rétrocompatibilité avec les intégrations historiques. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Événements à livrer. Concrètement obligatoire : un `[]` explicite est rejeté avec une erreur 400, et omettre ce champ crée une destination sans aucun abonnement qui ne reçoit rien. examples: session_updates: summary: Mises à jour du statut et des données de la session value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Mises à jour de la surveillance des transactions value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: Mises à jour des entités Utilisateur et Entreprise value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- Destination créée. `secret_shared_key` est le secret de signature HMAC — stockez-le maintenant. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Identifiant stable de la destination. À utiliser comme `{destination_uuid}` dans les appels ultérieurs. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- Secret de signature HMAC généré automatiquement et lié à cette destination (token de 43 caractères compatible URL). Utilisez-le pour vérifier les en-têtes de signature sur les webhooks entrants. Toujours renvoyé en intégralité aux appelants utilisant une clé API ; les utilisateurs de la Console doivent disposer de l'autorisation `read:webhooks`, faute de quoi ils verront une chaîne vide. secret_last4: type: string description: >- Quatre derniers caractères du secret de signature actuel de la destination, vous permettant de distinguer les secrets. Insuffisant pour vérifier une signature. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Défini pendant 24 heures après la rotation du secret de signature de la destination dans la Business Console. Jusqu'à cette échéance, chaque livraison vers la destination comporte également `X-Signature-Previous`, `X-Signature-V2-Previous` et `X-Signature-Simple-Previous`, générés avec le secret remplacé (voir [Vérification de signature](/fr/integration/webhooks#vérification-de-la-signature)). `null` si aucune rotation n'a eu lieu au cours des dernières 24 heures. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- E-mail du membre de la Business Console qui a créé la destination. `null` pour une destination créée avec une clé API. created_by_name: type: string nullable: true description: >- Nom du membre de la Business Console ayant créé la destination. `null` pour une destination créée avec une clé API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- État de la livraison. `failing` : 3 événements consécutifs ou plus ont échoué lors de leur première tentative de livraison depuis la dernière réponse réussie de la destination (voir `failing_streak`). `degraded` : pas en échec, mais une tentative de livraison a échoué au cours des dernières 24 heures et aucune tentative ultérieure n'a livré cet événement ; une nouvelle tentative ou un renvoi qui le livre efface cet état. `healthy` : aucun des deux. Indépendant de `enabled`. Une tentative échouée correspond à une réponse HTTP 400 ou supérieure, ou à une absence totale de réponse. failing_streak: type: integer description: >- Nombre d'événements consécutifs dont la première tentative de livraison a échoué depuis la dernière réponse réussie de la destination, au cours des 30 derniers jours. Les nouvelles tentatives ne sont pas comptabilisées, et toute tentative réussie, y compris une nouvelle tentative ou un renvoi, met fin à la série. `0` lorsqu'aucun événement n'a échoué depuis le dernier succès. failing_since: type: string format: date-time nullable: true description: >- Date et heure de la première tentative infructueuse de la série d'échecs en cours (`failing_streak`). `null` lorsque `failing_streak` vaut `0`. last_success_at: type: string format: date-time nullable: true description: >- Date et heure auxquelles la destination a répondu pour la dernière fois à une livraison avec un statut HTTP inférieur à 400, au cours des 30 derniers jours. `null` si ce n'est pas le cas dans cet intervalle. environment: type: string enum: - live - sandbox description: >- Environnement de l'application propriétaire de la destination. summary: type: object description: >- Métriques de livraison pour les derniers `metrics_window_days` (30) jours. `last_delivery_at` correspond à la tentative la plus récente, quelle que soit la date à laquelle elle a été effectuée. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- Durée en jours de la fenêtre couverte par les autres métriques récapitulatives. Toujours `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- Échec de la validation — généralement une URL en doublon, `subscribed_events` manquant/non valide ou un nom d'événement inconnu. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- Clé API manquante, mal formée, expirée ou limitée à une application différente. Une clé manquante renvoie `403` ; une clé erronée, révoquée ou expirée renvoie `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: Limite de débit dépassée ; réduisez la cadence et réessayez. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- Filtre d'événements pour cette destination de webhook. Didit ne livre que les webhooks dont le type d'événement correspond exactement à l'une de ces valeurs — il n'y a pas d'abonnement avec caractère générique. Lorsqu'elle est envoyée, la liste doit contenir au moins un événement valide (un `[]` explicite est rejeté avec une erreur 400) ; une destination dont la liste est vide (champ omis lors de la création) ne reçoit rien. Lors d'une mise à jour, la liste est entièrement remplacée, jamais fusionnée. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Nom d'événement webhook pris en charge. Utilisez ces chaînes exactes dans `subscribed_events` ; les valeurs non prises en charge sont rejetées. enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clé API de votre application, issue de Développeurs -> Clés API dans la Business Console. La clé principale dispose d'un accès complet. Une clé nommée peut être restreinte : aucun, lecture ou écriture par ressource, limitée à certains workflows ou aux sessions approuvées, à une liste d'adresses IP et à une date d'expiration. 401 signifie que la clé est incorrecte, révoquée ou expirée ; 403 signifie qu'aucune clé n'a été envoyée, que la clé n'a pas accès à cette ressource ou action, ou que la requête provient d'une adresse hors de sa liste d'IP ; 404 sur une route de session signifie que la session est hors des workflows ou des statuts de la clé. Une clé sans accès aux médias reçoit les URL d'images, de vidéos et de PDF à null, et une clé sans accès en écriture aux sessions reçoit les liens et tokens de session à null. Voir https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.