# Webhooks

Entenda quando cada webhook da Zild é enviado e consulte os payloads entregues ao seu endpoint.

Source: https://zild.ai/pt-BR/docs/apps/zild-admin/webhook

Webhooks permitem que sistemas externos recebam eventos da Zild em tempo real. Para cada configuração habilitada, a Zild envia uma requisição `POST` com `Content-Type: application/json` para a URL cadastrada.

## Como configurar

- No Zild Admin, abra **Integrações → Webhook**.
- Crie um webhook e informe um nome e uma URL HTTPS acessível pela internet.
- Selecione um dos eventos desta página e mantenha o webhook habilitado.
- Salve e valide o recebimento no sistema de destino.

O corpo depende do evento. Os nomes de propriedade abaixo correspondem aos objetos serializados pela API. Campos opcionais podem ser enviados como `null`, string vazia ou lista vazia, conforme o canal e a etapa do processamento.

## Visão geral dos eventos



<table class="api-params"><thead><tr><th>Valor</th><th>Evento</th><th>Momento do disparo</th><th>Payload</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>EvaluationResult</code></td><td>Zild Insight, após a análise de uma conversa.</td><td><code>WebhookEvaluationResultDto</code></td></tr><tr><td><code>2</code></td><td><code>ConversationEnded</code></td><td>Quando uma conversa é finalizada no Zild Assist, Zild Voice ou Zild Chat.</td><td><code>WebhookConversationEndedDto</code></td></tr><tr><td><code>3</code></td><td><code>ConversationDeleted</code></td><td>Quando uma conversa é excluída.</td><td>Envelope com <code>WebhookType</code> e <code>Conversation</code></td></tr><tr><td><code>4</code></td><td><code>CallTransferred</code></td><td>Quando uma chamada é transferida no Zild Voice.</td><td><code>WebhookCallTransferredDto</code></td></tr><tr><td><code>5</code>–<code>10</code></td><td>Eventos de documento</td><td>Durante o processamento no Zild Docs.</td><td>Objeto <code>Document</code></td></tr></tbody></table>



## 0 — EvaluationResult

**Conversation Analysis Ended.** É enviado após o Zild Insight concluir a análise de uma conversa. O payload contém canal, fila, checklist, nota final e o resultado de cada item avaliado.



```
{
  "Customer": "+5511999999999",
  "UserId": 42,
  "UserAgentCode": "AGT-042",
  "UserName": "Maria",
  "CommunicationChannelName": "WhatsApp",
  "CommunicationChannel": 1,
  "CreatedAt": "2026-09-23T12:00:00Z",
  "ChecklistName": "Qualidade do atendimento",
  "ChecklistId": 15,
  "QueueId": 7,
  "QueueName": "Suporte",
  "FinalScore": 92,
  "Duration": "00:04:12",
  "ChecklistItems": [
    {
      "ChecklistItemIntegrationId": "saudacao",
      "HighImportance": true,
      "Approved": true,
      "Feedback": "Saudação realizada corretamente.",
      "Score": 10,
      "MaxScore": 10,
      "Name": "Saudação inicial"
    }
  ]
}
```


`CommunicationChannel` é o valor numérico do canal. `FinalScore` e `Duration` podem ser nulos. O payload atual não inclui o ID da conversa.

## 2 — ConversationEnded

É enviado quando uma conversa é finalizada no Zild Assist, Zild Voice ou Zild Chat. O payload consolida os identificadores, cliente, canal, fila, usuário, agente, datas, resultado da chamada, resumo, mensagens, dados coletados e variáveis dinâmicas.



```
{
  "Customer": "+5511999999999",
  "ConversationId": "provider-conversation-id",
  "ConversationDbId": 8451,
  "UserId": 42,
  "UserAgentCode": "AGT-042",
  "UserName": "Maria",
  "CommunicationChannelName": "WhatsApp",
  "CommunicationChannel": 1,
  "CreatedAt": "2026-09-23T12:00:00Z",
  "QueueId": 7,
  "QueueName": "Suporte",
  "Duration": "00:04:12",
  "StartedAt": "2026-09-23T12:00:05Z",
  "FinishedAt": "2026-09-23T12:04:17Z",
  "AgentId": 19,
  "IntegrationType": "WhatsAppApi",
  "CallStatus": null,
  "DisconnectionReason": null,
  "CallSuccessful": false,
  "CallSid": null,
  "ConversationSummary": "Cliente solicitou a segunda via.",
  "ContactExternalId": "crm-123",
  "AudioUrl": "",
  "Messages": [
    {
      "CreatedAt": "2026-09-23T12:00:10Z",
      "From": "+5511999999999",
      "To": "Zild",
      "Content": "Preciso da segunda via.",
      "MessageType": 0,
      "MediaUrl": null,
      "MediaFileName": null
    }
  ],
  "DataCollection": [{ "Name": "protocolo", "Value": "ABC-123" }],
  "DynamicVariables": [{ "Name": "customer_name", "Value": "Ana" }]
}
```


`ConversationId` é o identificador da integração ou provedor; `ConversationDbId` é o ID numérico interno. Campos de telefonia são preenchidos principalmente no Zild Voice. Em chamadas que falham antes da interação, as listas podem ser vazias e o áudio pode não estar disponível.

## 3 — ConversationDeleted

É enviado depois que uma conversa é excluída. Diferentemente dos demais eventos, este payload possui um envelope: `WebhookType` identifica o evento e `Conversation` contém a entidade excluída.



```
{
  "WebhookType": "ConversationDeleted",
  "Conversation": {
    "Id": 8451,
    "Active": false,
    "Title": "Atendimento #8451",
    "LiveAgent": false,
    "From": "+5511999999999",
    "ContactId": 301,
    "ConversationId": "provider-conversation-id",
    "CreatedAt": "2026-09-23T12:00:00Z",
    "StartedAt": "2026-09-23T12:00:05Z",
    "FinishedAt": "2026-09-23T12:04:17Z",
    "TenantId": 10,
    "UserId": 42,
    "ConversationSummary": "Cliente solicitou a segunda via.",
    "CommunicationChannel": 1,
    "ConversationIntegrationType": 19,
    "Duration": "00:04:12",
    "QueueId": 7,
    "ConversationEndedReasonId": 2,
    "ConversationType": 0,
    "CallStatus": null,
    "DisconnectionReason": null,
    "CallSuccessful": false,
    "CallSid": null,
    "AgentId": 19
  }
}
```


A entidade pode conter outros campos operacionais e coleções de variáveis, dependendo do carregamento da conversa. Use `Conversation.Id` para identificar o registro excluído.

## 4 — CallTransferred

É enviado pelo Zild Voice quando uma ligação é transferida para outro agente, fila, número ou atendimento humano.



```
{
  "CallSid": "CA1234567890",
  "ConversationId": null,
  "AgentId": 19,
  "UserId": null,
  "QueueId": null,
  "CustomerPhoneNumber": "+5511999999999",
  "TransferTo": ["+551133334444"],
  "CallerId": "+551130001000",
  "TransferAnalysis": "Cliente solicitou atendimento humano.",
  "TransferredAt": "2026-09-23T12:03:00Z",
  "TransferCustomData": "{\"protocol\":\"ABC-123\"}"
}
```


`TransferTo` contém um ou mais destinos. `TransferAnalysis` registra o contexto da decisão e `TransferCustomData` preserva dados adicionais. `ConversationId`, `UserId` e `QueueId` são opcionais.

## 5–10 — Webhooks de documento

Os seis eventos do Zild Docs enviam o próprio objeto `Document` depois que o status é atualizado. O formato é o mesmo para todos; mudam o momento e o valor de `DocumentStatusType`.



<table class="api-params"><thead><tr><th>Valor</th><th>Evento</th><th>Quando é enviado</th><th><code>DocumentStatusType</code></th></tr></thead><tbody><tr><td><code>5</code></td><td><code>DocumentNew</code></td><td>Quando um novo documento é criado para processamento e OCR.</td><td><code>0</code> — <code>New</code></td></tr><tr><td><code>6</code></td><td><code>DocumentInProgress</code></td><td>Quando o job inicia o processamento do documento.</td><td><code>1</code> — <code>InProgress</code></td></tr><tr><td><code>7</code></td><td><code>DocumentTextExtracted</code></td><td>Quando o Zild Docs extrai o texto e os dados do arquivo.</td><td><code>2</code> — <code>TextExtracted</code></td></tr><tr><td><code>8</code></td><td><code>DocumentError</code></td><td>Quando ocorre erro durante a extração do texto.</td><td><code>3</code> — <code>Error</code></td></tr><tr><td><code>9</code></td><td><code>DocumentCompleted</code></td><td>Quando a extração e a revisão do texto por IA são finalizadas.</td><td><code>4</code> — <code>Completed</code></td></tr><tr><td><code>10</code></td><td><code>DocumentCancelled</code></td><td>Quando o usuário ou o processamento cancela o documento.</td><td><code>5</code> — <code>Cancelled</code></td></tr></tbody></table>



## Payload dos eventos de documento



```
{
  "Id": 123,
  "TenantId": 10,
  "Title": "Contrato.pdf",
  "Description": null,
  "ExtractedText": "Texto extraído do documento...",
  "QuantityPages": 8,
  "AnalysisText": "Texto revisado pela IA...",
  "FileUrl": "https://storage.example/contrato.pdf",
  "DocumentStatusId": 0,
  "DocumentType": 2,
  "CreatedAt": "2026-09-23T12:00:00Z",
  "AnalizedAt": "2026-09-23T12:01:30Z",
  "DocumentChecklistId": 7,
  "Private": false,
  "CreatedByUserId": 18,
  "DocumentStatusType": 4
}
```




<table class="api-params"><thead><tr><th>Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>Id</code></td><td>Identificador do documento. Use-o como chave de idempotência.</td></tr><tr><td><code>ExtractedText</code></td><td>Texto obtido do arquivo; pode estar nulo antes da extração.</td></tr><tr><td><code>QuantityPages</code></td><td>Quantidade de páginas detectada.</td></tr><tr><td><code>AnalysisText</code></td><td>Resultado da revisão por IA ou mensagem associada ao cancelamento/erro.</td></tr><tr><td><code>DocumentType</code></td><td><code>0</code> Image, <code>1</code> Word, <code>2</code> PDF ou <code>3</code> Text.</td></tr><tr><td><code>AnalizedAt</code></td><td>Data da análise; pode ser nula até a conclusão.</td></tr><tr><td><code>DocumentStatusType</code></td><td>Status que originou o evento: de <code>0</code> a <code>5</code>, conforme a tabela acima.</td></tr></tbody></table>



## Boas práticas de recebimento

- Responda rapidamente com HTTP `2xx` e processe tarefas demoradas de forma assíncrona.
- Faça o processamento de forma idempotente usando `ConversationDbId`, `Conversation.Id`, `CallSid` ou `Document.Id`.
- Aceite campos opcionais nulos e novos campos compatíveis no futuro.
- Proteja o endpoint com HTTPS e não coloque segredos na URL.
- Evite registrar texto extraído, mensagens, áudio ou dados pessoais sem necessidade e política de retenção.