# Webhooks disponíveis

Configure webhooks para receber eventos da Zild, incluindo todas as mudanças de status de documentos no Zild Docs.

Source: https://zild.ai/pt-BR/docs/api-reference/webhooks

## Como funcionam

Webhooks notificam seu sistema quando um evento ocorre na Zild. Para cada cadastro habilitado, a plataforma envia uma requisição `POST` com `Content-Type: application/json` para a URL configurada. O corpo varia conforme o evento.

Cadastre um webhook com `POST /Webhook`, informe uma URL HTTPS acessível pela internet, mantenha `enable` como `true` e selecione o valor numérico de `webhookType`.



```
{
  "enable": true,
  "name": "Documento concluído",
  "webhookType": 9,
  "url": "https://example.com/webhooks/zild"
}
```



## Eventos disponíveis



<table class="api-params"><thead><tr><th>Valor</th><th>Evento</th><th>Quando é enviado</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>EvaluationResult</code></td><td>Quando um resultado de avaliação fica disponível.</td></tr><tr><td><code>2</code></td><td><code>ConversationEnded</code></td><td>Quando uma conversa é encerrada.</td></tr><tr><td><code>3</code></td><td><code>ConversationDeleted</code></td><td>Quando uma conversa é excluída.</td></tr><tr><td><code>4</code></td><td><code>CallTransferred</code></td><td>Quando uma chamada é transferida.</td></tr><tr><td><code>5</code></td><td><code>DocumentNew</code></td><td>Quando um documento é criado com status <code>New</code>.</td></tr><tr><td><code>6</code></td><td><code>DocumentInProgress</code></td><td>Quando o processamento muda para <code>InProgress</code>.</td></tr><tr><td><code>7</code></td><td><code>DocumentTextExtracted</code></td><td>Quando o texto do documento foi extraído.</td></tr><tr><td><code>8</code></td><td><code>DocumentError</code></td><td>Quando o processamento termina com erro.</td></tr><tr><td><code>9</code></td><td><code>DocumentCompleted</code></td><td>Quando o processamento é concluído.</td></tr><tr><td><code>10</code></td><td><code>DocumentCancelled</code></td><td>Quando o processamento é cancelado.</td></tr></tbody></table>



## Webhooks de documentos

Os seis eventos de documento acompanham o ciclo de vida do Zild Docs. O payload é o próprio objeto `Document` após a atualização de status. Use `Id` como chave de idempotência e `DocumentStatusType` para confirmar o estado recebido.



<table class="api-params"><thead><tr><th>Status</th><th>Valor</th><th>Evento correspondente</th></tr></thead><tbody><tr><td><code>New</code></td><td><code>0</code></td><td><code>DocumentNew</code></td></tr><tr><td><code>InProgress</code></td><td><code>1</code></td><td><code>DocumentInProgress</code></td></tr><tr><td><code>TextExtracted</code></td><td><code>2</code></td><td><code>DocumentTextExtracted</code></td></tr><tr><td><code>Error</code></td><td><code>3</code></td><td><code>DocumentError</code></td></tr><tr><td><code>Completed</code></td><td><code>4</code></td><td><code>DocumentCompleted</code></td></tr><tr><td><code>Cancelled</code></td><td><code>5</code></td><td><code>DocumentCancelled</code></td></tr></tbody></table>



## Exemplo de payload de documento



```
{
  "Id": 123,
  "TenantId": 45,
  "Title": "Contrato.pdf",
  "Description": null,
  "ExtractedText": "...",
  "QuantityPages": 8,
  "AnalysisText": "...",
  "FileUrl": "https://...",
  "DocumentStatusId": 0,
  "DocumentType": 2,
  "CreatedAt": "2026-09-23T12:00:00Z",
  "AnalizedAt": "2026-09-23T12:01:30Z",
  "DocumentChecklistId": 7,
  "Private": false,
  "CreatedByUserId": 18,
  "DocumentStatusType": 4
}
```


Os campos podem conter `null` conforme a etapa de processamento. Não use `FileUrl`, título ou data como identificador único.

## Recebimento seguro

- Responda rapidamente com um status `2xx` e processe trabalhos demorados de forma assíncrona.
- Trate entregas repetidas de forma idempotente.
- Restrinja a URL a HTTPS e não inclua segredos nela.
- Registre o ID do documento, o tipo de evento e o horário, evitando persistir conteúdo sensível sem necessidade.
- Monitore respostas não `2xx` no seu endpoint.