# Available webhooks

Configure webhooks to receive Zild events, including every Zild Docs document status change.

Source: https://zild.ai/en-US/docs/api-reference/webhooks

## How they work

Webhooks notify your system when an event occurs in Zild. For each enabled registration, the platform sends a `POST` request with `Content-Type: application/json` to the configured URL. The request body depends on the event.

Create a webhook with `POST /Webhook`, provide an internet-accessible HTTPS URL, keep `enable` set to `true`, and select the numeric `webhookType` value.



```
{
  "enable": true,
  "name": "Document completed",
  "webhookType": 9,
  "url": "https://example.com/webhooks/zild"
}
```



## Available events



<table class="api-params"><thead><tr><th>Value</th><th>Event</th><th>When it is sent</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>EvaluationResult</code></td><td>When an evaluation result becomes available.</td></tr><tr><td><code>2</code></td><td><code>ConversationEnded</code></td><td>When a conversation ends.</td></tr><tr><td><code>3</code></td><td><code>ConversationDeleted</code></td><td>When a conversation is deleted.</td></tr><tr><td><code>4</code></td><td><code>CallTransferred</code></td><td>When a call is transferred.</td></tr><tr><td><code>5</code></td><td><code>DocumentNew</code></td><td>When a document is created with the <code>New</code> status.</td></tr><tr><td><code>6</code></td><td><code>DocumentInProgress</code></td><td>When processing changes to <code>InProgress</code>.</td></tr><tr><td><code>7</code></td><td><code>DocumentTextExtracted</code></td><td>When document text has been extracted.</td></tr><tr><td><code>8</code></td><td><code>DocumentError</code></td><td>When processing ends with an error.</td></tr><tr><td><code>9</code></td><td><code>DocumentCompleted</code></td><td>When processing completes.</td></tr><tr><td><code>10</code></td><td><code>DocumentCancelled</code></td><td>When processing is cancelled.</td></tr></tbody></table>



## Document webhooks

The six document events follow the Zild Docs lifecycle. The payload is the `Document` object itself after its status is updated. Use `Id` as the idempotency key and `DocumentStatusType` to confirm the received state.



<table class="api-params"><thead><tr><th>Status</th><th>Value</th><th>Matching event</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>



## Document payload example



```
{
  "Id": 123,
  "TenantId": 45,
  "Title": "Contract.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
}
```


Fields may contain `null` depending on the processing stage. Do not use `FileUrl`, title, or date as a unique identifier.

## Safe receiving

- Respond quickly with a `2xx` status and process long-running work asynchronously.
- Handle repeated deliveries idempotently.
- Restrict the URL to HTTPS and do not include secrets in it.
- Log the document ID, event type, and time while avoiding unnecessary storage of sensitive content.
- Monitor non-`2xx` responses from your endpoint.