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

Como funciona subscribed_events

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

Catálogo de eventos

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

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
label
string
obrigatório

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

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

URL HTTPS que receberá pedidos POST. Deve ser único entre os destinos da aplicação. Utilize um endpoint estável e protegido: a Didit tenta novamente entregas que falharam num esquema de espera progressiva.

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

Quando for false, o destino é guardado, mas a Didit não enviará quaisquer webhooks para o mesmo. Útil para configurações de teste que queira manter em pausa.

webhook_version
enum<string>

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

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

Eventos a entregar. Efetivamente obrigatório: um [] explícito é rejeitado com 400, e omitir o campo cria um destino sem subscrições que não recebe nada.

Minimum array length: 1

Nome de evento de webhook suportado. Utilize estas strings exatas em subscribed_events; valores não suportados 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 — guarde-o agora.

uuid
string<uuid>

Identificador estável de destino. Utilize como {destination_uuid} em chamadas subsequentes.

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 associado a este destino (token de 43 carateres seguro para URL). Utilize-o para verificar os cabeçalhos de assinatura nos webhooks recebidos. Devolvido sempre na totalidade a quem efetua chamadas com chave de API; os utilizadores da consola precisam da permissão read:webhooks, caso contrário verão uma string vazia.

secret_last4
string

Últimos quatro carateres do segredo de assinatura atual do destino, para que possa distinguir os segredos. Não são suficientes para verificar uma assinatura.

previous_secret_expires_at
string<date-time> | null

Definido durante 24 horas após o segredo de assinatura do destino ser alterado na Business Console. Até esse momento, cada entrega para o 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 da assinatura). null quando não ocorreu qualquer rotação nas últimas 24 horas.

subscribed_events
enum<string>[]

Filtro de eventos para este destino do webhook. O Didit entrega apenas webhooks cujo tipo de evento corresponda exatamente a um destes valores — não existe subscrição com carateres universais. Ao ser enviada, a lista deve conter pelo menos um evento válido (um [] explícito é rejeitado com 400); um destino cuja lista esteja vazia (campo omitido na criação) não recebe nada. Na atualização, a lista é substituída integralmente, nunca fundida.

Minimum array length: 1

Nome de evento de webhook suportado. Utilize estas strings exatas em subscribed_events; valores não suportados 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 da Business Console que criou o destino. null para um destino criado com uma chave de API.

created_by_name
string | null

Nome do membro da 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>

Estado da entrega. failing: 3 ou mais eventos consecutivos falharam a primeira tentativa de entrega desde que o destino respondeu com sucesso pela última vez (consulte failing_streak). degraded: não está a falhar, mas uma tentativa de entrega falhou nas últimas 24 horas e nenhuma tentativa posterior entregou esse evento; uma nova tentativa ou reenvio bem-sucedido limpa este estado. healthy: nenhum dos anteriores. Independente de enabled. Uma tentativa falhada é aquela respondida com HTTP 400 ou superior, ou que não obteve qualquer resposta.

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

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

failing_since
string<date-time> | null

Quando foi feita a primeira tentativa falhada da atual failing_streak. null quando failing_streak é 0.

last_success_at
string<date-time> | null

Quando o destino respondeu pela última vez a uma entrega com um estado HTTP inferior a 400, nos últimos 30 dias. null se não o tiver feito nesse período.

environment
enum<string>

Ambiente da aplicação a que pertence o destino.

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

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

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