Webhooks

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

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

Valor	Evento	Momento do disparo	Payload
`0`	`EvaluationResult`	Zild Insight, após a análise de uma conversa.	`WebhookEvaluationResultDto`
`2`	`ConversationEnded`	Quando uma conversa é finalizada no Zild Assist, Zild Voice ou Zild Chat.	`WebhookConversationEndedDto`
`3`	`ConversationDeleted`	Quando uma conversa é excluída.	Envelope com `WebhookType` e `Conversation`
`4`	`CallTransferred`	Quando uma chamada é transferida no Zild Voice.	`WebhookCallTransferredDto`
`5`–`10`	Eventos de documento	Durante o processamento no Zild Docs.	Objeto `Document`

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.

Valor	Evento	Quando é enviado	`DocumentStatusType`
`5`	`DocumentNew`	Quando um novo documento é criado para processamento e OCR.	`0` — `New`
`6`	`DocumentInProgress`	Quando o job inicia o processamento do documento.	`1` — `InProgress`
`7`	`DocumentTextExtracted`	Quando o Zild Docs extrai o texto e os dados do arquivo.	`2` — `TextExtracted`
`8`	`DocumentError`	Quando ocorre erro durante a extração do texto.	`3` — `Error`
`9`	`DocumentCompleted`	Quando a extração e a revisão do texto por IA são finalizadas.	`4` — `Completed`
`10`	`DocumentCancelled`	Quando o usuário ou o processamento cancela o documento.	`5` — `Cancelled`

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
}

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

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.