# Webhooks

Learn when each Zild webhook is sent and review the payloads delivered to your endpoint.

Source: https://zild.ai/en-US/docs/apps/zild-admin/webhook

For each enabled webhook, Zild sends a `POST` request with `Content-Type: application/json` to the configured URL. Optional fields may be `null`, empty strings, or empty arrays depending on the channel and processing stage.

## How to configure

- In Zild Admin, open **Integrations → Webhook**.
- Create a webhook and provide a name and an internet-accessible HTTPS URL.
- Select an event, enable the webhook, and save it.
- Validate delivery in the destination system.

## Event overview



<table class="api-params"><thead><tr><th>Value</th><th>Event</th><th>Trigger</th><th>Payload</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>EvaluationResult</code></td><td>After Zild Insight analyzes a conversation.</td><td><code>WebhookEvaluationResultDto</code></td></tr><tr><td><code>2</code></td><td><code>ConversationEnded</code></td><td>When a Zild Assist, Voice, or Chat conversation ends.</td><td><code>WebhookConversationEndedDto</code></td></tr><tr><td><code>3</code></td><td><code>ConversationDeleted</code></td><td>When a conversation is deleted.</td><td><code>WebhookType</code> and <code>Conversation</code> envelope</td></tr><tr><td><code>4</code></td><td><code>CallTransferred</code></td><td>When Zild Voice transfers a call.</td><td><code>WebhookCallTransferredDto</code></td></tr><tr><td><code>5</code>–<code>10</code></td><td>Document events</td><td>During Zild Docs processing.</td><td><code>Document</code></td></tr></tbody></table>



## 0 — EvaluationResult

**Conversation Analysis Ended.** Contains customer, user, communication channel, creation time, checklist, queue, final score, duration, and `ChecklistItems`. Each item contains `ChecklistItemIntegrationId`, `HighImportance`, `Approved`, `Feedback`, `Score`, `MaxScore`, and `Name`. The current payload does not include a conversation ID.



```
{
  "Customer": "+15551234567",
  "UserId": 42,
  "UserAgentCode": "AGT-042",
  "UserName": "Maria",
  "CommunicationChannelName": "WhatsApp",
  "CommunicationChannel": 1,
  "CreatedAt": "2026-09-23T12:00:00Z",
  "ChecklistName": "Service quality",
  "ChecklistId": 15,
  "QueueId": 7,
  "QueueName": "Support",
  "FinalScore": 92,
  "Duration": "00:04:12",
  "ChecklistItems": [{ "ChecklistItemIntegrationId": "greeting", "HighImportance": true, "Approved": true, "Feedback": "Correct greeting.", "Score": 10, "MaxScore": 10, "Name": "Initial greeting" }]
}
```



## 2 — ConversationEnded

Contains conversation identifiers, customer, channel, queue, user, agent, timestamps, call outcome, summary, messages, collected data, and dynamic variables.



```
{
  "Customer": "+15551234567",
  "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": "Support",
  "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": "Customer requested a duplicate invoice.",
  "ContactExternalId": "crm-123",
  "AudioUrl": "",
  "Messages": [{ "CreatedAt": "2026-09-23T12:00:10Z", "From": "+15551234567", "To": "Zild", "Content": "I need a duplicate invoice.", "MessageType": 0, "MediaUrl": null, "MediaFileName": null }],
  "DataCollection": [{ "Name": "protocol", "Value": "ABC-123" }],
  "DynamicVariables": [{ "Name": "customer_name", "Value": "Ana" }]
}
```


`ConversationId` is the provider identifier; `ConversationDbId` is Zild's numeric ID. Telephony fields are mainly populated for Zild Voice.

## 3 — ConversationDeleted

This event uses an envelope. `WebhookType` is `ConversationDeleted`, and `Conversation` is the deleted entity with fields such as `Id`, `Active`, `Title`, `From`, `ContactId`, provider conversation ID, timestamps, tenant and user IDs, summary, channel, integration type, duration, queue, end reason, conversation type, call result, and agent ID.



```
{
  "WebhookType": "ConversationDeleted",
  "Conversation": { "Id": 8451, "Active": false, "From": "+15551234567", "ConversationId": "provider-conversation-id", "TenantId": 10, "UserId": 42, "CommunicationChannel": 1, "QueueId": 7, "AgentId": 19 }
}
```



## 4 — CallTransferred



```
{
  "CallSid": "CA1234567890",
  "ConversationId": null,
  "AgentId": 19,
  "UserId": null,
  "QueueId": null,
  "CustomerPhoneNumber": "+15551234567",
  "TransferTo": ["+15557654321"],
  "CallerId": "+15550001000",
  "TransferAnalysis": "Customer requested a human operator.",
  "TransferredAt": "2026-09-23T12:03:00Z",
  "TransferCustomData": "{\"protocol\":\"ABC-123\"}"
}
```


`TransferTo` contains one or more destinations. `ConversationId`, `UserId`, and `QueueId` may be null.

## 5–10 — Document webhooks

All six events send the same `Document` object after status changes.



<table class="api-params"><thead><tr><th>Value</th><th>Event</th><th>Trigger</th><th>Status</th></tr></thead><tbody><tr><td><code>5</code></td><td><code>DocumentNew</code></td><td>Created for OCR and processing.</td><td><code>0</code> New</td></tr><tr><td><code>6</code></td><td><code>DocumentInProgress</code></td><td>Processing job starts.</td><td><code>1</code> InProgress</td></tr><tr><td><code>7</code></td><td><code>DocumentTextExtracted</code></td><td>Text and data are extracted.</td><td><code>2</code> TextExtracted</td></tr><tr><td><code>8</code></td><td><code>DocumentError</code></td><td>Text extraction fails.</td><td><code>3</code> Error</td></tr><tr><td><code>9</code></td><td><code>DocumentCompleted</code></td><td>Extraction and AI review finish.</td><td><code>4</code> Completed</td></tr><tr><td><code>10</code></td><td><code>DocumentCancelled</code></td><td>User or processing cancels the document.</td><td><code>5</code> Cancelled</td></tr></tbody></table>



## Document payload



```
{
  "Id": 123,
  "TenantId": 10,
  "Title": "Contract.pdf",
  "Description": null,
  "ExtractedText": "Extracted document text...",
  "QuantityPages": 8,
  "AnalysisText": "AI-reviewed text...",
  "FileUrl": "https://storage.example/contract.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
}
```


Use `Id` for idempotency. `ExtractedText` and `AnalizedAt` may be null before their processing stages. `DocumentType` is `0` Image, `1` Word, `2` PDF, or `3` Text.

## Receiving practices

- Respond quickly with HTTP `2xx` and process long-running work asynchronously.
- Process idempotently using the event's stable ID.
- Accept nullable and future compatible fields.
- Use HTTPS and do not put secrets in the URL.
- Avoid retaining messages, extracted text, audio, or personal data without a clear need.