Webhooks de entidades: eventos de usuario y empresa

Cada cambio en el estado o en los datos de perfil de una entidad de usuario o de empresa emite un webhook para que tu sistema pueda reaccionar en tiempo real. Usa los webhooks de entidades para sincronizar datos de perfil, propagar bloqueos a otros sistemas o activar flujos de cumplimiento posteriores.

Catálogo de eventos

Evento	Disparador
`user.status.updated`	Cambia el estado de una entidad de usuario (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`)
`user.data.updated`	Cambian los campos de perfil de una entidad de usuario (nombre, fecha de nacimiento, retrato, contadores agregados, metadatos)
`business.status.updated`	Cambia el estado de una entidad de empresa
`business.data.updated`	Cambian los campos de perfil de una entidad de empresa (razón social, número de registro, país, contadores)

activity.created se acepta en subscribed_events y está disponible en el probador Try Webhook, pero actualmente Didit no lo entrega para el tráfico de producción. No implementes una réplica de la línea de tiempo basándote en este evento.

Didit también emite eventos de sesión, de transacción y de sesión de empresa que hacen referencia a campos de entidades. Consulta:

Webhooks de KYB: eventos de sesiones de empresa
Webhooks de Monitorización de transacciones: eventos de transacciones
Referencia de webhooks: verificación de firma, reintentos, destinos de webhook

Estructura del payload

Los webhooks de entidades son planos: no hay envoltorio data ni clave event. Lee webhook_type para enrutar el evento.

{
  "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"
}

Campo	Descripción
`vendor_user_id` / `vendor_business_id`	Identificador de Didit para la entidad. Los eventos `business.*` usan `vendor_business_id`.
`vendor_data`	Tu identificador para la entidad.
`status`	`ACTIVE`, `FLAGGED` o `BLOCKED`.
`previous_status`	Solo en `*.status.updated`.
`changed_fields` y `changes`	Solo en `*.data.updated`.
`created_at`	Segundos Unix en que se actualizó la entidad por última vez.
`timestamp`	Segundos Unix en que Didit envió el webhook.

`user.status.updated` / `business.status.updated`

Se dispara en cada cambio de estado. El payload incluye status y previous_status. No indica por qué cambió el estado: abre la entidad en la consola si necesitas conocer la causa.

`user.data.updated` / `business.data.updated`

Se dispara cuando cambian campos de perfil. changed_fields enumera los campos que cambiaron y changes contiene los valores previous y current de cada uno.

{
  "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 }
  }
}

Los campos que pueden aparecer en changed_fields son:

Usuario: 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.
Empresa: 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.

Usa changed_fields y changes para sincronizar solo los campos que cambiaron.

Entrega, reintentos y firma

Todos los webhooks de entidades siguen el contrato de entrega estándar:

Firmados con HMAC-SHA256 en el encabezado X-Signature-V2 (recomendado), con la secret_shared_key del destino. También se envían X-Signature y el obsoleto X-Signature-Simple, junto con X-Timestamp.
Reintentados hasta 2 veces, después de aproximadamente 1 minuto y aproximadamente 4 minutos, cuando tu endpoint responde con 5xx o 404, se agota el tiempo de espera o no se puede conectar. La referencia de webhooks describe la política completa.
Idempotente: cada webhook tiene un event_id único en el payload; elimina los duplicados por tu parte.

Consulta la Referencia de webhooks para configurar destinos y ver ejemplos de código de verificación de firma.

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"
    ]
  }'

Próximos pasos

Referencia de webhooks

Destinos, firmas, reintentos y verificación.

Crear destino

Registra un nuevo endpoint de webhook.

Operaciones de usuario

Cambios que disparan webhooks de usuario.

Visión general

Precios

Flujos y verificación

Revisión y operaciones

Entidades (usuarios y empresas)

Ajustes y personalización

Seguridad y cumplimiento

Didit Academy

Recursos

Webhooks de entidades: eventos de usuario y empresa

Catálogo de eventos

Estructura del payload

`user.status.updated` / `business.status.updated`

`user.data.updated` / `business.data.updated`

Entrega, reintentos y firma

Suscribirse

Próximos pasos

Referencia de webhooks

Crear destino

Operaciones de usuario

​Catálogo de eventos

​Estructura del payload

​user.status.updated / business.status.updated

​user.data.updated / business.data.updated

​Entrega, reintentos y firma

​Suscribirse

​Próximos pasos

Referencia de webhooks

Crear destino

Operaciones de usuario

Catálogo de eventos

Estructura del payload

`user.status.updated` / `business.status.updated`

`user.data.updated` / `business.data.updated`

Entrega, reintentos y firma

Suscribirse

Próximos pasos