> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Criar destino de webhook via API > Registre um destino de webhook na Didit com versão, eventos inscritos e segredo de assinatura próprio. Gestão de webhooks via API, paga por chamada. Prompt da API para criar um destino de webhook Copiar o prompt para a área de transferência \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

Example call:
curl -X POST "https://verification.didit.me/v3/webhook/destinations/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Production session webhooks",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated"]
}'

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
Colar em 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| Evento | Assine quando você precisar de | | - | - | | `status.updated` | Mudanças de status de sessões de Verificação de usuários (KYC) ou Verificação de empresas (KYB). Os payloads de KYB incluem `session_kind: "business"` e `business_session_id`. | | `data.updated` | Dados de verificação da sessão corrigidos ou atualizados após a criação, como edições do revisor em dados de KYC, Comprovante de endereço ou KYB. | | `user.status.updated` | Mudança de status de uma entidade User, por exemplo `ACTIVE`, `FLAGGED` ou `BLOCKED`. | | `user.data.updated` | Mudanças no perfil, contadores, metadados, documentos ou campos agregados de verificação de uma entidade User. | | `business.status.updated` | Mudança de status de uma entidade Business, por exemplo após revisão manual, resultados de KYB ou uma ação de lista de bloqueio. | | `business.data.updated` | Mudanças no perfil, contadores, metadados, campos de registro ou campos agregados de verificação de uma entidade Business. | | `activity.created` | Aceito em `subscribed_events` e coberto pelo **Try Webhook**, mas a Didit atualmente não o entrega para tráfego de produção. | | `transaction.created` | Uma transação do Monitoramento de transações é criada e a avaliação inicial das regras é concluída. | | `transaction.status.updated` | Uma transação muda de status após a aplicação de regras, revisão de um analista, remediação, atualizações de provedores ou ações pela API ou pelo console; também é enviado uma vez quando uma triagem de cripto repetida em segundo plano é concluída. | | `travel_rule.status.updated` | Uma troca de [Travel Rule](https://docs.didit.me/pt-br/transaction-monitoring/travel-rule.md) muda de status. | | `workflow.compliance_changed` | O status de conformidade de um workflow publicado muda após uma reavaliação. | | `transaction_rule_suggestions.created` | Uma execução de sugestões de regras propõe novas alterações de regras. |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](https://docs.didit.me/pt-br/integration/webhooks.md#tipos-de-evento).Conjuntos de assinatura comuns:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```Para exemplos de payload e código de assinatura, consulte o [guia de webhooks](https://docs.didit.me/pt-br/integration/webhooks.md). ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Criar destino do webhook description: >- Cria um destino do webhook. A resposta inclui o segredo de assinatura HMAC `secret_shared_key`, gerado automaticamente (também pode ser lido depois via `GET /v3/webhook/destinations/{destination_uuid}/`). Sempre envie `subscribed_events` com pelo menos um evento (sem curingas): uma lista vazia explícita é rejeitada com 400, e omitir o campo cria um destino inscrito em nada, que nunca recebe um webhook. O par `(application, url)` deve ser único entre os destinos da aplicação. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nome legível exibido em Console → Webhooks. Ajuda a distinguir destinos quando você tem vários (por exemplo, "Prod", "Staging mirror"). url: type: string format: uri description: >- 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. maxLength: 2000 enabled: type: boolean default: true description: >- 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: type: string enum: - v1 - v2 - v3 description: >- 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. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- 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. examples: session_updates: summary: Atualizações de status e de dados da sessão value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Atualizações do monitoramento de transações value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: Atualizações de entidades de usuário e empresa value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: >- Destino criado. `secret_shared_key` é o segredo de assinatura HMAC: armazene-o agora. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Identificador estável do destino. Use como `{destination_uuid}` nas chamadas seguintes. label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- 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: type: string description: >- Ú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: type: string format: date-time nullable: true description: >- 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](/pt-br/integration/webhooks#verificação-de-assinatura)). `null` quando nenhuma rotação ocorreu nas últimas 24 horas. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- E-mail do membro do Business Console que criou o destino. `null` para um destino criado com uma chave de API. created_by_name: type: string nullable: true description: >- Nome do membro do Business Console que criou o destino. `null` para um destino criado com uma chave de API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- 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. failing_streak: type: integer description: >- 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: type: string format: date-time nullable: true description: >- Quando foi feita a primeira tentativa com falha do `failing_streak` atual. `null` quando `failing_streak` é `0`. last_success_at: type: string format: date-time nullable: true description: >- 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: type: string enum: - live - sandbox description: Ambiente da aplicação proprietária do destino. summary: type: object description: >- Métricas de entrega dos últimos `metrics_window_days` (30) dias. `last_delivery_at` é a tentativa mais recente, independentemente de quando foi feita. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: >- Duração, em dias, da janela coberta pelas demais métricas de resumo. Sempre `30`. examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- Falha na validação. Geralmente uma URL duplicada, `subscribed_events` ausente ou inválido, ou um nome de evento desconhecido. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- Chave de API ausente, malformada, expirada ou vinculada a outra aplicação. Uma chave ausente retorna `403`; uma chave incorreta, revogada ou expirada retorna `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: Limite de requisições excedido; aguarde e tente novamente. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- 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. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Nome de evento de webhook compatível. Use exatamente estas strings em `subscribed_events`; valores não compatíveis são rejeitados. enum: - 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.