Saltar al contenido principal
POST
curl
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

También se aceptan las familias de eventos Investigator (investigator.*) y Authentication (auth.*). Todos los eventos y sus payloads se enumeran en Webhooks. Conjuntos de suscripciones habituales:
Para ver ejemplos de payloads y código de firma, consulta la guía de webhooks.

Autorizaciones

x-api-key
string
header
requerido

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.

Cuerpo

application/json
label
string
requerido

Nombre legible que se muestra en Console → Webhooks. Ayuda a distinguir los destinos cuando tienes varios (p. ej., "Prod", "Staging mirror").

Maximum string length: 255
url
string<uri>
requerido

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).

Maximum string length: 2000
enabled
boolean
predeterminado:true

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
enum<string>

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.

Opciones disponibles:
v1,
v2,
v3
subscribed_events
enum<string>[]

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.

Minimum array length: 1

Nombre de evento de webhook admitido. Usa exactamente estas cadenas en subscribed_events; los valores no admitidos se rechazan.

Opciones disponibles:
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
Ejemplo:

Respuesta

Destino creado. secret_shared_key es el secreto de firma HMAC: guárdalo ahora.

uuid
string<uuid>

Identificador estable del destino. Úsalo como {destination_uuid} en las llamadas posteriores.

label
string
url
string<uri>
enabled
boolean
webhook_version
enum<string>
Opciones disponibles:
v1,
v2,
v3
secret_shared_key
string

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
string

Ú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
string<date-time> | null

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). null cuando no se ha producido ninguna rotación en las últimas 24 horas.

subscribed_events
enum<string>[]

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.

Minimum array length: 1

Nombre de evento de webhook admitido. Usa exactamente estas cadenas en subscribed_events; los valores no admitidos se rechazan.

Opciones disponibles:
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
Ejemplo:
created_by_email
string | null

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
string | null

Nombre del miembro de Business Console que creó el destino. null para un destino creado con una clave de API.

created_at
string<date-time>
updated_at
string<date-time>
health_status
enum<string>

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.

Opciones disponibles:
healthy,
degraded,
failing
failing_streak
integer

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
string<date-time> | null

Cuándo se realizó el primer intento fallido de la failing_streak actual. null cuando failing_streak es 0.

last_success_at
string<date-time> | null

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
enum<string>

Entorno de la aplicación a la que pertenece el destino.

Opciones disponibles:
live,
sandbox
summary
object

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ó.

Última modificación el 1 de noviembre de 2026