Pular para o conteúdo principal
POST
curl
Os destinos de webhook permitem enviar diferentes eventos da Didit para diferentes URLs. Cada destino tem suas próprias secret_shared_key, webhook_version e lista subscribed_events.

Como funciona o subscribed_events

subscribed_events é um array obrigatório com nomes exatos de eventos. A Didit entrega um webhook a este destino somente quando o webhook_type do payload corresponde a um dos valores do array.
  • Inclua pelo menos um evento.
  • Use apenas os nomes de eventos aceitos listados abaixo.
  • Adicione todos os eventos que você quer receber: não existe valor curinga como * ou all.
  • Para encaminhar diferentes áreas do produto a diferentes sistemas, crie vários destinos com listas subscribed_events diferentes.

Catálogo de eventos

As famílias de eventos do Investigator (investigator.*) e de Authentication (auth.*) também são aceitas. Todos os eventos e seus payloads estão listados em Webhooks. Conjuntos de assinatura comuns:
Para exemplos de payload e código de assinatura, consulte o guia de webhooks.

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
label
string
obrigatório

Nome legível exibido em Console → Webhooks. Ajuda a distinguir destinos quando você tem vários (por exemplo, "Prod", "Staging mirror").

Maximum string length: 255
url
string<uri>
obrigatório

URL HTTPS que receberá requisições POST. Deve ser única entre os destinos da aplicação. Use um endpoint estável e protegido: a Didit tenta novamente as entregas com falha seguindo um cronograma de backoff.

Maximum string length: 2000
enabled
boolean
padrão:true

Quando false, o destino é salvo, mas a Didit não enviará nenhum webhook para ele. Útil para configurações de staging que você quer manter em espera.

webhook_version
enum<string>

Versão do esquema de payload que a Didit enviará. v3 é o formato atual/recomendado; as versões anteriores são mantidas para compatibilidade com integrações legadas.

Opções disponíveis:
v1,
v2,
v3
subscribed_events
enum<string>[]

Eventos a entregar. Na prática, obrigatório: um [] explícito é rejeitado com 400, e omitir o campo cria um destino sem assinaturas que não recebe nada.

Minimum array length: 1

Nome de evento de webhook compatível. Use exatamente estas strings em subscribed_events; valores não compatíveis são rejeitados.

Opções disponíveis:
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
Exemplo:

Resposta

Destino criado. secret_shared_key é o segredo de assinatura HMAC: armazene-o agora.

uuid
string<uuid>

Identificador estável do destino. Use como {destination_uuid} nas chamadas seguintes.

label
string
url
string<uri>
enabled
boolean
webhook_version
enum<string>
Opções disponíveis:
v1,
v2,
v3
secret_shared_key
string

Segredo de assinatura HMAC gerado automaticamente e vinculado a este destino (token seguro para URL com 43 caracteres). Use-o para verificar os cabeçalhos de assinatura nos webhooks recebidos. É sempre retornado por completo para chamadores com chave de API; usuários do Console precisam da permissão read:webhooks, caso contrário veem uma string vazia.

secret_last4
string

Últimos quatro caracteres do segredo de assinatura atual do destino, para que você possa distinguir os segredos. Não é suficiente para verificar uma assinatura.

previous_secret_expires_at
string<date-time> | null

Definido por 24 horas após a rotação do segredo de assinatura do destino no Business Console. Até esse momento, toda entrega ao destino também inclui X-Signature-Previous, X-Signature-V2-Previous e X-Signature-Simple-Previous, gerados com o segredo substituído (consulte Verificação de assinatura). null quando nenhuma rotação ocorreu nas últimas 24 horas.

subscribed_events
enum<string>[]

Filtro de eventos deste destino do webhook. A Didit entrega apenas webhooks cujo tipo de evento corresponde exatamente a um destes valores; não existe assinatura curinga. Quando enviada, a lista deve conter pelo menos um evento válido (um [] explícito é rejeitado com 400); um destino cuja lista está vazia (campo omitido na criação) não recebe nada. Na atualização, a lista é substituída por inteiro, nunca mesclada.

Minimum array length: 1

Nome de evento de webhook compatível. Use exatamente estas strings em subscribed_events; valores não compatíveis são rejeitados.

Opções disponíveis:
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
Exemplo:
created_by_email
string | null

E-mail do membro do Business Console que criou o destino. null para um destino criado com uma chave de API.

created_by_name
string | null

Nome do membro do Business Console que criou o destino. null para um destino criado com uma chave de API.

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

Saúde das entregas. failing: 3 ou mais eventos consecutivos falharam na primeira tentativa de entrega desde a última vez que o destino respondeu com sucesso (consulte failing_streak). degraded: não está em falha, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou um reenvio que o entregue remove esse estado. healthy: nenhum dos dois. Independe de enabled. Uma tentativa com falha é aquela respondida com HTTP 400 ou superior, ou que não recebeu resposta.

Opções disponíveis:
healthy,
degraded,
failing
failing_streak
integer

Quantos eventos consecutivos falharam na primeira tentativa de entrega desde a última resposta bem-sucedida do destino, nos últimos 30 dias. Novas tentativas não são contadas, e qualquer tentativa bem-sucedida, incluindo uma nova tentativa ou um reenvio, encerra a sequência. 0 quando nenhum evento falhou desde o último sucesso.

failing_since
string<date-time> | null

Quando foi feita a primeira tentativa com falha do failing_streak atual. null quando failing_streak é 0.

last_success_at
string<date-time> | null

Quando o destino respondeu pela última vez a uma entrega com um status HTTP abaixo de 400, nos últimos 30 dias. null se isso não ocorreu nesse período.

environment
enum<string>

Ambiente da aplicação proprietária do destino.

Opções disponíveis:
live,
sandbox
summary
object

Métricas de entrega dos últimos metrics_window_days (30) dias. last_delivery_at é a tentativa mais recente, independentemente de quando foi feita.

Última modificação em 1 de novembro de 2026