> ## 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. # API para crear un destino de webhook > Registra un nuevo destino de webhook de Didit con versión, eventos suscritos y secreto de firma propio. Gestión programática, pago por llamada. Prompt de la API para crear un destino de webhook Copiar el prompt al portapapeles \

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

\
Pegar en Los destinos de webhook te permiten enviar distintos eventos de Didit a distintas URL. Cada destino tiene su propia `secret_shared_key`, su propio `webhook_version` y su propia lista `subscribed_events`.## Cómo funciona `subscribed_events``subscribed_events` es un array obligatorio de nombres de eventos exactos. Didit entrega un webhook a este destino solo cuando el `webhook_type` del payload coincide con uno de los valores del array.- Incluye al menos un evento. - Usa solo los nombres de eventos admitidos que se indican a continuación. - Añade todos los eventos que quieras recibir; no existe ningún valor comodín como `*` o `all`. - Para dirigir distintas áreas de producto a distintos sistemas, crea varios destinos con distintas listas de `subscribed_events`.## Catálogo de eventos| Evento | Suscríbete cuando necesites | | - | - | | `status.updated` | Cambios de estado de sesiones de Verificación de usuarios (KYC) o de Verificación de empresas (KYB). Los payloads de KYB incluyen `session_kind: "business"` y `business_session_id`. | | `data.updated` | Los datos de verificación de la sesión se corrigen o actualizan después de su creación, por ejemplo, ediciones realizadas por un revisor en los datos de KYC, de comprobante de domicilio o de KYB. | | `user.status.updated` | Una entidad User cambia de estado, por ejemplo, a `ACTIVE`, `FLAGGED` o `BLOCKED`. | | `user.data.updated` | Cambian el perfil, los contadores, los metadatos, los documentos o los campos de verificación agregados de una entidad User. | | `business.status.updated` | Una entidad Business cambia de estado, por ejemplo, después de una revisión manual, de resultados de KYB o de una acción de lista de bloqueo. | | `business.data.updated` | Cambian el perfil, los contadores, los metadatos, los campos de registro o los campos de verificación agregados de una entidad Business. | | `activity.created` | Se acepta en `subscribed_events` y está cubierto por **Try Webhook**, pero actualmente Didit no lo entrega para el tráfico en producción. | | `transaction.created` | Se crea una transacción de Monitorización de transacciones y se completa su evaluación inicial de reglas. | | `transaction.status.updated` | Una transacción cambia de estado tras la aplicación de reglas, una revisión de un analista, una remediación, actualizaciones del proveedor o acciones desde la API o la consola; también se envía una vez cuando se completa un análisis de criptomonedas que se reintentó en segundo plano. | | `travel_rule.status.updated` | Un intercambio de [Travel Rule](https://docs.didit.me/es/transaction-monitoring/travel-rule.md) cambia de estado. | | `workflow.compliance_changed` | El estado de cumplimiento de un flujo publicado cambia después de una reevaluación. | | `transaction_rule_suggestions.created` | Una ejecución de sugerencias de reglas propone nuevos cambios de reglas. |También se aceptan las familias de eventos Investigator (`investigator.*`) y Authentication (`auth.*`). Todos los eventos y sus payloads se enumeran en [Webhooks](https://docs.didit.me/es/integration/webhooks.md#tipos-de-eventos).Conjuntos de suscripciones habituales:```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" ] } ```Para ver ejemplos de payloads y código de firma, consulta la [guía de webhooks](https://docs.didit.me/es/integration/webhooks.md). ## OpenAPI ````yaml es/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificación de identidad. Autentícate con el encabezado x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Crear destino de webhook description: >- Crea un destino de webhook. La respuesta incluye `secret_shared_key`, el secreto de firma HMAC generado automáticamente (también se puede leer más tarde mediante `GET /v3/webhook/destinations/{destination_uuid}/`). Envía siempre `subscribed_events` con al menos un evento (sin comodines): una lista vacía explícita se rechaza con 400, y omitir el campo crea un destino sin suscripción a ningún evento, que nunca recibe un webhook. El par `(application, url)` debe ser único entre los destinos de la aplicación. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nombre legible que se muestra en Console → Webhooks. Ayuda a distinguir los destinos cuando tienes varios (p. ej., "Prod", "Staging mirror"). url: type: string format: uri description: >- URL HTTPS que recibirá solicitudes `POST`. Debe ser única entre los destinos de la aplicación. Usa un endpoint estable y protegido: Didit reintenta las entregas fallidas con esperas progresivas (backoff). maxLength: 2000 enabled: type: boolean default: true description: >- Cuando es `false`, el destino se guarda, pero Didit no le enviará ningún webhook. Útil para configuraciones de staging que quieras mantener en pausa. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Versión del esquema del payload que enviará Didit. `v3` es el formato actual y recomendado; las versiones anteriores se mantienen por compatibilidad con integraciones heredadas. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Eventos que se entregan. En la práctica es obligatorio: un `[]` explícito se rechaza con 400, y si omites el campo se crea un destino sin suscripciones que no recibe nada. examples: session_updates: summary: Actualizaciones de estado y de datos de la sesión value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Actualizaciones de la monitorización de transacciones 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: Actualizaciones de entidades de usuario y 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: >- Destino creado. `secret_shared_key` es el secreto de firma HMAC: guárdalo ahora. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Identificador estable del destino. Úsalo como `{destination_uuid}` en las llamadas posteriores. 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: >- Secreto de firma HMAC generado automáticamente y vinculado a este destino (token seguro para URL de 43 caracteres). Úsalo para verificar los encabezados de firma de los webhooks entrantes. Siempre se devuelve completo a quienes llaman con una clave de API; los usuarios de la Console necesitan el permiso `read:webhooks` y, de lo contrario, ven una cadena vacía. secret_last4: type: string description: >- Últimos cuatro caracteres del secreto de firma actual del destino, para que puedas distinguir los secretos. No basta para verificar una firma. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Se establece durante 24 horas después de rotar el secreto de firma del destino en la Business Console. Hasta ese momento, cada entrega al destino también incluye `X-Signature-Previous`, `X-Signature-V2-Previous` y `X-Signature-Simple-Previous`, generados con el secreto sustituido (consulta [Verificación de firma](/es/integration/webhooks#verificación-de-firma)). `null` cuando no se ha producido ninguna rotación en las últimas 24 horas. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- Correo electrónico del miembro de Business Console que creó el destino. `null` para un destino creado con una clave de API. created_by_name: type: string nullable: true description: >- Nombre del miembro de Business Console que creó el destino. `null` para un destino creado con una clave de API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Estado de las entregas. `failing`: 3 o más eventos consecutivos fallaron en su primer intento de entrega desde la última vez que el destino respondió correctamente (consulta `failing_streak`). `degraded`: el destino no está fallando, pero un intento de entrega falló en las últimas 24 horas y ningún intento posterior ha entregado ese evento; un reintento o un reenvío que lo entregue elimina este estado. `healthy`: ninguno de los dos casos anteriores. Es independiente de `enabled`. Un intento fallido es aquel que recibe una respuesta HTTP 400 o superior, o que no recibe ninguna respuesta. failing_streak: type: integer description: >- Cuántos eventos consecutivos fallaron en su primer intento de entrega desde la última vez que el destino respondió correctamente, dentro de los últimos 30 días. Los reintentos no se cuentan, y cualquier intento correcto, incluido un reintento o un reenvío, pone fin a la racha. `0` cuando ningún evento ha fallado desde el último éxito. failing_since: type: string format: date-time nullable: true description: >- Cuándo se realizó el primer intento fallido de la `failing_streak` actual. `null` cuando `failing_streak` es `0`. last_success_at: type: string format: date-time nullable: true description: >- Cuándo el destino respondió por última vez a una entrega con un estado HTTP inferior a 400, dentro de los últimos 30 días. `null` si no lo ha hecho en ese periodo. environment: type: string enum: - live - sandbox description: Entorno de la aplicación a la que pertenece el destino. summary: type: object description: >- Métricas de entrega de los últimos `metrics_window_days` (30) días. `last_delivery_at` es el intento más reciente, independientemente de cuándo se realizó. 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: >- Duración en días de la ventana que cubren las demás métricas del resumen. Siempre `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ón ha fallado; normalmente por una URL duplicada, `subscribed_events` ausente o no válido, o un nombre de evento desconocido. 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: >- Clave de API ausente, con formato incorrecto, expirada o asociada a otra aplicación. Si falta la clave, se devuelve `403`; si es incorrecta, está revocada o ha expirado, se devuelve `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: Límite de solicitudes superado; espera y reintenta. 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: >- Filtro de eventos de este destino de webhook. Didit entrega solo los webhooks cuyo tipo de evento coincide exactamente con uno de estos valores: no existe una suscripción comodín. Si se envía, la lista debe contener al menos un evento válido (un `[]` explícito se rechaza con 400). Un destino con la lista vacía (campo omitido al crearlo) no recibe nada. Al actualizar, la lista se reemplaza por completo y nunca se combina. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Nombre de evento de webhook admitido. Usa exactamente estas cadenas en `subscribed_events`; los valores no admitidos se rechazan. 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 clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.