Webhooks

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

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

Value	Event	Trigger	Payload
`0`	`EvaluationResult`	After Zild Insight analyzes a conversation.	`WebhookEvaluationResultDto`
`2`	`ConversationEnded`	When a Zild Assist, Voice, or Chat conversation ends.	`WebhookConversationEndedDto`
`3`	`ConversationDeleted`	When a conversation is deleted.	`WebhookType` and `Conversation` envelope
`4`	`CallTransferred`	When Zild Voice transfers a call.	`WebhookCallTransferredDto`
`5`–`10`	Document events	During Zild Docs processing.	`Document`

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.

Value	Event	Trigger	Status
`5`	`DocumentNew`	Created for OCR and processing.	`0` New
`6`	`DocumentInProgress`	Processing job starts.	`1` InProgress
`7`	`DocumentTextExtracted`	Text and data are extracted.	`2` TextExtracted
`8`	`DocumentError`	Text extraction fails.	`3` Error
`9`	`DocumentCompleted`	Extraction and AI review finish.	`4` Completed
`10`	`DocumentCancelled`	User or processing cancels the document.	`5` Cancelled

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.