> ## 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. # Crear destinació de webhook: API > Registra una destinació de webhook de Didit amb versió, esdeveniments subscrits i secret de signatura propi. Pagament per crida. Indicació de l'API per crear una destinació del webhook Copia el prompt al porta-retalls \

\`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.`

\
Enganxa a Els destins de webhook et permeten enviar diferents esdeveniments de Didit a URL diferents. Cada destí té el seu propi `secret_shared_key`, `webhook_version` i la seva llista `subscribed_events`.## Com funciona `subscribed_events``subscribed_events` és un array obligatori de noms d'esdeveniment exactes. Didit envia un webhook a aquesta destinació del webhook només quan el `webhook_type` del payload coincideix amb un dels valors de l'array.- Inclou com a mínim un esdeveniment. - Fes servir només els noms d'esdeveniment compatibles que apareixen a continuació. - Afegeix tots els esdeveniments que vulguis rebre; no hi ha cap valor comodí com `*` o `all`. - Per encaminar àrees de producte diferents a sistemes diferents, crea diverses destinacions del webhook amb llistes `subscribed_events` diferents.## Catàleg d'esdeveniments| Esdeveniment | Subscriu-t'hi quan ho necessitis | | - | - | | `status.updated` | Canvis d'estat d'una sessió de verificació d'usuaris (KYC) o de verificació d'empreses (KYB). Els payloads de KYB inclouen `session_kind: "business"` i `business_session_id`. | | `data.updated` | Les dades de verificació de la sessió es corregeixen o s'actualitzen després de la creació, per exemple quan un revisor edita les dades de KYC, de comprovant de domicili o de KYB. | | `user.status.updated` | Una entitat d'usuari canvia d'estat, per exemple `ACTIVE`, `FLAGGED` o `BLOCKED`. | | `user.data.updated` | Canvien el perfil, els comptadors, les metadades, els documents o els camps de verificació agregats d'una entitat d'usuari. | | `business.status.updated` | Una entitat d'empresa canvia d'estat, per exemple després de la revisió manual, dels resultats de KYB o d'una acció de llista de bloqueig. | | `business.data.updated` | Canvien el perfil, els comptadors, les metadades, els camps de registre o els camps de verificació agregats d'una entitat d'empresa. | | `activity.created` | S'accepta a `subscribed_events` i està coberta per **Try Webhook**, però Didit actualment no l'envia per al trànsit en entorn de producció. | | `transaction.created` | Es crea una transacció de Monitoratge de transaccions i s'ha completat la seva avaluació inicial de regles. | | `transaction.status.updated` | Una transacció canvia d'estat després de l'aplicació de regles, de la revisió per part d'analistes, de la remediació o d'actualitzacions dels proveïdors, o d'accions de l'API o de la consola; també s'envia una vegada quan acaba un cribratge de criptoactius reintentat en segon pla. | | `travel_rule.status.updated` | Un intercanvi de [Travel Rule](https://docs.didit.me/ca/transaction-monitoring/travel-rule.md) canvia d'estat. | | `workflow.compliance_changed` | L'estat de compliment d'un flux de treball publicat canvia després d'una reavaluació. | | `transaction_rule_suggestions.created` | Una execució de suggeriments de regles proposa noves modificacions de regles. |Les famílies d'esdeveniments `investigator.*` i `auth.*` també s'accepten. Tots els esdeveniments i els seus payloads s'enumeren a [Webhooks](https://docs.didit.me/ca/integration/webhooks.md#tipus-d’esdeveniments).Combinacions habituals de subscripció:```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" ] } ```Per a exemples de payloads i codi de signatura, consulta la [guia de webhooks](https://docs.didit.me/ca/integration/webhooks.md). ## OpenAPI ````yaml ca/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Crea una destinació del webhook description: >- Crea una destinació del webhook. La resposta inclou el secret de signatura HMAC `secret_shared_key` generat automàticament (també consultable posteriorment mitjançant `GET /v3/webhook/destinations/{destination_uuid}/`). Envia sempre `subscribed_events` amb almenys un esdeveniment (sense caràcters comodí): una llista buida explícita es rebutja amb un 400, i ometre el camp crea una destinació no subscrita a res, que no rep mai cap webhook. El parell `(application, url)` ha de ser únic entre les destinacions de l'aplicació. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nom fàcil de llegir mostrat a Console → Webhooks. Ajuda a distingir les destinacions quan en tens diverses (p. ex., "Prod", "Staging mirror"). url: type: string format: uri description: >- URL HTTPS que rebrà sol·licituds `POST`. Ha de ser única entre les destinacions de l'aplicació. Fes servir un endpoint estable i protegit: Didit reintenta els lliuraments fallits seguint un calendari de reintents amb espera progressiva. maxLength: 2000 enabled: type: boolean default: true description: >- Quan és `false`, la destinació es desa però Didit no hi enviarà cap webhook. Útil per a configuracions de preproducció que vulguis mantenir pausades. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Versió de l'esquema del payload que enviarà Didit. `v3` és el format actual/recomanat; les versions anteriors es mantenen per garantir la compatibilitat amb les integracions heretades. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Esdeveniments a lliurar. Pràcticament obligatori: un `[]` explícit es rebutja amb 400, i ometre el camp crea una destinació sense subscripcions que no rep res. examples: session_updates: summary: Actualitzacions de dades i de l'estat de la sessió value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Actualitzacions del monitoratge de transaccions 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: Actualitzacions de les entitats d'usuari i d'empresa 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: >- Destinació creada. `secret_shared_key` és el secret de signatura HMAC; desa'l ara. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Identificador de destinació estable. Utilitza'l com a `{destination_uuid}` en crides posteriors. 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 signatura HMAC generat automàticament i vinculat a aquesta destinació (token de 43 caràcters segur per a URL). Utilitza'l per verificar les capçaleres de signatura als webhooks entrants. Sempre es retorna complet als qui criden amb clau d'API; els usuaris de la consola necessiten el permís `read:webhooks`, altrament veuen una cadena buida. secret_last4: type: string description: >- Últims quatre caràcters del secret de signatura actual de la destinació, perquè puguis distingir els secrets. No són suficients per verificar una signatura. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Establert durant 24 hores després que el secret de signatura de la destinació es roti a la Business Console. Fins aquest moment, cada lliurament a la destinació també inclou `X-Signature-Previous`, `X-Signature-V2-Previous` i `X-Signature-Simple-Previous`, generats amb el secret substituït (consulta [Verificació de la signatura](/ca/integration/webhooks#verificació-de-la-signatura)). `null` quan no s'ha produït cap rotació en les darreres 24 hores. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- Correu electrònic del membre de la Business Console que ha creat la destinació. `null` per a una destinació creada amb una clau d'API. created_by_name: type: string nullable: true description: >- Nom del membre de la Business Console que ha creat la destinació. `null` per a una destinació creada amb una clau d'API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Estat del lliurament. `failing`: 3 o més esdeveniments consecutius han fallat en el seu primer intent de lliurament des que la destinació va respondre satisfactòriament per darrera vegada (consulta `failing_streak`). `degraded`: no és failing, però un intent de lliurament ha fallat en les darreres 24 hores i cap intent posterior ha lliurat aquest esdeveniment; un reintent o reenviament que el lliuri neteja aquest estat. `healthy`: cap dels dos. Independent d'`enabled`. Un intent fallit és un que ha rebut una resposta HTTP 400 o superior, o que no ha rebut cap resposta. failing_streak: type: integer description: >- Quants esdeveniments consecutius han fallat en el seu primer intent de lliurament des que la destinació va respondre satisfactòriament per última vegada, durant els darrers 30 dies. Els reintents no es comptabilitzen, i qualsevol intent satisfactori, inclòs un reintent o un reenviament, posa fi a la ratxa. `0` quan cap esdeveniment ha fallat des de l'últim èxit. failing_since: type: string format: date-time nullable: true description: >- Quan es va fer el primer intent fallit de la `failing_streak` actual. `null` quan `failing_streak` és `0`. last_success_at: type: string format: date-time nullable: true description: >- Quan la destinació va respondre per darrera vegada a un lliurament amb un estat HTTP inferior a 400, en els darrers 30 dies. `null` si no ho ha fet en aquest interval. environment: type: string enum: - live - sandbox description: Entorn de l'aplicació propietària de la destinació. summary: type: object description: >- Mètriques de lliurament dels darrers `metrics_window_days` (30) dies. `last_delivery_at` és l'intent més recent, independentment de quan es va fer. 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: >- Durada en dies de la finestra que cobreixen les altres mètriques de resum. Sempre és `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: >- La validació ha fallat: normalment un URL duplicat, `subscribed_events` absent o no vàlid, o un nom d'esdeveniment desconegut. 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: >- Falta la clau d'API, està mal formada, ha caducat o està assignada a una aplicació diferent. Si falta la clau es retorna `403`; una clau incorrecta, revocada o caducada retorna `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: >- S'ha superat el límit de freqüència; redueix el ritme de les sol·licituds i reintenta-ho. 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'esdeveniments per a aquesta destinació del webhook. Didit només lliura webhooks el tipus d'esdeveniment dels quals coincideix exactament amb un d'aquests valors; no hi ha subscripció amb caràcters comodí. Quan s'envia, la llista ha de contenir almenys un esdeveniment vàlid (un `[]` explícit es rebutja amb 400); una destinació amb la llista buida (camp omès en crear-se) no rep res. En actualitzar, la llista es reemplaça completament, mai es fusiona. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Nom d'esdeveniment de webhook admès. Utilitza aquestes cadenes exactes a `subscribed_events`; els valors no admesos es rebutgen. 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 clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.