Webhooks de entidades: eventos de utilizador e de empresa

Sempre que o estado ou os dados de perfil de uma entidade User ou Business mudam, é emitido um webhook para que o seu sistema reaja em tempo real. Use os webhooks de entidades para sincronizar dados de perfil, propagar bloqueios para outros sistemas ou acionar fluxos de conformidade a jusante.

Catálogo de eventos

Evento	Acionador
`user.status.updated`	O estado de uma entidade User muda (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`)
`user.data.updated`	Os campos de perfil de uma entidade User mudam (nome, data de nascimento, retrato, contadores agregados, metadados)
`business.status.updated`	O estado de uma entidade Business muda
`business.data.updated`	Os campos de perfil de uma entidade Business mudam (razão social, número de registo, país, contadores)

activity.created é aceite em subscribed_events e coberto pelo testador Try Webhook, mas a Didit não o envia atualmente para tráfego em produção. Não construa uma sincronização de cronologia com base neste evento.

A Didit também emite eventos de sessão, de transação e de sessão empresarial que referenciam campos de entidades. Consulte:

Webhooks de KYB: eventos de sessões empresariais
Webhooks de Monitorização de transações: eventos de transações
Referência de webhooks: verificação de assinaturas, novas tentativas, destinos

Formato dos payloads

Os webhooks de entidades são planos: não existe um wrapper data nem uma chave event. Leia webhook_type para encaminhar o 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	Descrição
`vendor_user_id` / `vendor_business_id`	Identificador da Didit para a entidade. Os eventos `business.*` usam `vendor_business_id`.
`vendor_data`	O seu identificador para a entidade.
`status`	`ACTIVE`, `FLAGGED` ou `BLOCKED`.
`previous_status`	Apenas em `*.status.updated`.
`changed_fields` e `changes`	Apenas em `*.data.updated`.
`created_at`	Segundos Unix em que a entidade foi atualizada pela última vez.
`timestamp`	Segundos Unix em que a Didit enviou o webhook.

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

É disparado em cada alteração de estado. O payload inclui status e previous_status. Não indica o motivo da alteração de estado: se precisar da causa, abra a entidade na consola.

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

É disparado quando os campos de perfil mudam. changed_fields lista os campos que mudaram e changes contém o valor previous e o valor current de cada um.

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

Os campos que podem aparecer em changed_fields são:

User: 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.
Business: 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.

Use changed_fields e changes para sincronizar apenas os campos que mudaram.

Entrega, novas tentativas e assinatura

Todos os webhooks de entidades seguem o contrato de entrega padrão:

Assinados com HMAC-SHA256 no cabeçalho X-Signature-V2 (recomendado), com o secret_shared_key do destino. São também enviados X-Signature e o X-Signature-Simple, descontinuado, juntamente com X-Timestamp.
São feitas novas tentativas até 2 vezes, após cerca de 1 minuto e cerca de 4 minutos, quando o seu endpoint responde com 5xx ou 404, excede o tempo limite ou não consegue estabelecer ligação. A referência de webhooks tem a política completa.
Idempotentes: cada webhook tem um event_id único no payload; elimine duplicados do seu lado.

Consulte Referência de webhooks para a configuração de destinos e exemplos de código de verificação de assinaturas.

Subscrição

Subscreva os eventos de entidades num destino de webhook através da Management API ou da Business Console:

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 passos

Referência de webhooks

Destinos, assinaturas, novas tentativas e verificação.

Criar destino

Registe um novo endpoint de webhook.

Operações sobre utilizadores

Alterações que acionam webhooks de utilizadores.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (utilizadores e empresas)

Definições e personalização

Segurança e conformidade

Didit Academy

Recursos

Webhooks de entidades: eventos de utilizador e de empresa

Catálogo de eventos

Formato dos payloads

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

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

Entrega, novas tentativas e assinatura

Subscrição

Próximos passos

Referência de webhooks

Criar destino

Operações sobre utilizadores

​Catálogo de eventos

​Formato dos payloads

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

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

​Entrega, novas tentativas e assinatura

​Subscrição

​Próximos passos

Referência de webhooks

Criar destino

Operações sobre utilizadores

Catálogo de eventos

Formato dos payloads

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

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

Entrega, novas tentativas e assinatura

Subscrição

Próximos passos