> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.simz.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.simz.com/_mcp/server.

# Webhook Events

> Receive SimZ call lifecycle and audit events at your endpoint.

SimZ can send webhook events to your application when a call completes or when a call audit finishes. Use these events to sync call outcomes, recording metadata, lead custom data, and audit results.

## Event types

| Event                  | When it fires                                             | Best for                                             | Requires review prompt? |
| ---------------------- | --------------------------------------------------------- | ---------------------------------------------------- | ----------------------- |
| `call.completed`       | After recording completes and the call record is updated. | Call metadata, recording metadata, lead custom data. | No                      |
| `call.audit.completed` | After audit/review processing finishes.                   | Qualification and review outcomes.                   | Yes                     |

## `call.completed`

This event fires after SimZ stores call recording and metadata. It is independent from audit processing.

```json
{
  "event": "call.completed",
  "callId": "call_1777920072301_12514",
  "agentId": "d5c58cfd-ddb4-47ba-8c85-d68a8f7f36e3",
  "companyId": "comp_0005",
  "status": "Completed",
  "timestamp": "2026-05-19T15:02:14.781Z",
  "call": {
    "direction": "Outbound",
    "callerNumber": "+15551234567",
    "toNumber": "+15557654321",
    "callDateTime": "2026-05-19T15:00:02.000Z",
    "durationSeconds": 132,
    "billedDurationMinutes": 3,
    "recordingUrl": "call_1777920072301_12514.mp3",
    "twilioCallSid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "lead": {
    "customData": {
      "leadId": "LEAD-001",
      "campaignTag": "spring-2026"
    }
  }
}
```

## `call.audit.completed`

This event fires after SimZ finishes review/audit processing. The `audit` object depends on your agent review prompt and custom fields schema.

```json
{
  "event": "call.audit.completed",
  "callId": "call_1777920072301_12514",
  "agentId": "d5c58cfd-ddb4-47ba-8c85-d68a8f7f36e3",
  "companyId": "comp_0005",
  "status": "successful",
  "timestamp": "2026-05-19T15:06:41.220Z",
  "lead": {
    "customData": {
      "leadId": "LEAD-001",
      "campaignTag": "spring-2026"
    }
  },
  "audit": {
    "qualified": true,
    "reason": "Customer confirmed interest and scheduled a callback"
  }
}
```

## Common fields

| Field             | Type           | Description                                                        |
| ----------------- | -------------- | ------------------------------------------------------------------ |
| `event`           | string         | Event name.                                                        |
| `callId`          | string         | SimZ internal call ID.                                             |
| `agentId`         | string         | Agent that handled the call.                                       |
| `companyId`       | string         | Company ID.                                                        |
| `status`          | string         | Call lifecycle status or audit classification, depending on event. |
| `timestamp`       | string         | ISO 8601 generation timestamp.                                     |
| `lead.customData` | object or null | Client custom data passed with the lead or call.                   |

## Delivery behavior

Webhook deliveries are signed when a secret is configured, retried according to webhook settings, and logged in the SimZ webhook management UI.