Webhooks de entidades: eventos de usuário e empresa

Toda alteração no status ou nos dados de perfil de uma entidade User ou Business gera 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 subsequentes.

Catálogo de eventos

Evento	Gatilho
`user.status.updated`	O status 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 status de uma entidade Business muda
`business.data.updated`	Os campos de perfil de uma entidade Business mudam (razão social, número de registro, país, contadores)

activity.created é aceito em subscribed_events e pode ser testado no Try Webhook, mas a Didit não o entrega atualmente em produção. Não use esse evento para espelhar linhas do tempo.

A Didit também emite eventos de sessão, de transação e de sessão de empresa que fazem referência a campos de entidades. Veja:

Webhooks de KYB — eventos de sessão de empresa
Webhooks de Monitoramento de transações — eventos de transação
Referência de webhooks — verificação de assinatura, novas tentativas, destinos

Formatos de payload

Os webhooks de entidades são planos: não há 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`	Somente em `*.status.updated`.
`changed_fields` e `changes`	Somente em `*.data.updated`.
`created_at`	Segundos Unix de quando a entidade foi atualizada pela última vez.
`timestamp`	Segundos Unix de quando a Didit despachou o webhook.

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

É disparado a cada mudança de status. O payload traz status e previous_status. Ele não informa por que o status mudou: abra a entidade no console se você precisar saber a causa.

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

É disparado quando 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 somente os campos que mudaram.

Entrega, novas tentativas e assinatura

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

Assinado com HMAC-SHA256 no cabeçalho X-Signature-V2 (recomendado), usando o secret_shared_key do destino. X-Signature e o obsoleto X-Signature-Simple também são enviados, junto com X-Timestamp.
Repetido 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 falha ao conectar. A referência de webhooks traz a política completa.
Idempotente — todo webhook tem um event_id único no payload; faça a deduplicação do seu lado.

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

Inscrever-se em eventos

Inscreva-se em eventos de entidades em um destino de webhook pela Management API ou pelo 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

Registre um novo endpoint de webhook.

Operações de usuário

Alterações que disparam webhooks de usuário.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (usuários e empresas)

Configurações e personalização

Segurança e conformidade

Didit Academy

Recursos

Webhooks de entidades: eventos de usuário e empresa

Catálogo de eventos

Formatos de payload

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

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

Entrega, novas tentativas e assinatura

Inscrever-se em eventos

Próximos passos

Referência de webhooks

Criar destino

Operações de usuário

​Catálogo de eventos

​Formatos de payload

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

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

​Entrega, novas tentativas e assinatura

​Inscrever-se em eventos

​Próximos passos

Referência de webhooks

Criar destino

Operações de usuário

Catálogo de eventos

Formatos de payload

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

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

Entrega, novas tentativas e assinatura

Inscrever-se em eventos

Próximos passos