# Call Webhooks

Call webhooks send phone.systems(TM) call events to your own server in real
time. Use them to update a CRM, start a workflow when a call starts or ends,
store call records, or process call recordings and [AI Call
Insights](../Call-analytics/call-history.html#ps3-call-history-ai)
results in your own systems.

Each event is sent as a signed HTTPS request to the URL that you configure in
**Settings > Webhooks**. Your server verifies the signature, stores the event,
and responds with a `2xx` status code.

## Availability and access

- Only the DIDWW account owner can manage the webhook. Open phone.systems(TM)
  from the DIDWW User Panel to open the **Webhooks** page, view the secret,
  and add or delete the webhook. PBX users with the **agent** role cannot see
  the page. See [User Accesses](user-accesses.html).
- Each account has one webhook URL.
- The URL must use HTTPS. Addresses in private, loopback, and link-local
  networks are not accepted, and redirects are not followed.

## How call webhooks work

phone.systems(TM) sends two kinds of events for each call:

| Kind | Events | When they are sent |
| --- | --- | --- |
| Live call events | - `call.started` - `call.connected` - `call.ended` | While the call is in progress: when it starts ringing, when it is answered, and when it ends. |
| CDR events | - `call.cdr.created` - `call.cdr.attachment_created` - `call.cdr.attachment_failed` - `call.cdr.transcript_created` - `call.cdr.summary_created` - `call.cdr.scoring_created` - `call.cdr.ai_processing_failed` - `call.cdr.updated` - `call.cdr.resolved` | After the call. `call.cdr.created` delivers each call detail record (CDR). The other CDR events are follow-up events. They report later results for a CDR: files, AI Call Insights and [AI Call Scoring](../Call-analytics/ai-call-scoring.html#ps3-ai-call-scoring) results, [tags and notes](call-tags.html#ps3-settings-call-tags), and [lost call resolution](../Call-analytics/call-history.html#ps3-call-history-resolve-lost-calls). For when each event is sent, see [Event types](webhooks/webhook-event-reference.html#ps3-webhooks-event-types). |

All events of one call share the same `global_tag`. A call can produce
several CDRs, for example when it is transferred. Each CDR has its own
`uuid`, and the last CDR of the call has `"final": true`.

```
        %%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px",
    "actorBkg": "#e0f2fe",
    "actorBorder": "#38bdf8",
    "actorTextColor": "#1f2d3d",
    "actorLineColor": "#38bdf8",
    "signalColor": "#0f766e",
    "signalTextColor": "#1f2d3d",
    "labelBoxBkgColor": "#ccfbf1",
    "labelBoxBorderColor": "#14b8a6",
    "labelTextColor": "#1f2d3d",
    "noteBkgColor": "#fef3c7",
    "noteBorderColor": "#f59e0b",
    "noteTextColor": "#1f2d3d",
    "sequenceNumberColor": "#ffffff"
  }
}}%%

sequenceDiagram
   autonumber
   participant ps as phone.systems(TM)
   participant server as Your server

   ps->>server: call.started
   server-->>ps: 2xx
   ps->>server: call.connected
   server-->>ps: 2xx
   ps->>server: call.ended
   server-->>ps: 2xx
   ps->>server: call.cdr.created
   server-->>ps: 2xx
   ps->>server: Follow-up events, for example call.cdr.transcript_created
   server-->>ps: 2xx
   Note over server: Verify the signature of each request<br/>and skip events whose id was already processed
```

If your server does not respond with a `2xx` status code, phone.systems(TM)
retries the request. Events of the same call are delivered in order. For
details, see [Webhook delivery and troubleshooting](webhooks/webhook-delivery-and-troubleshooting.html).

## Limitations

- Calls that ended before the webhook was added produce no events and are
  never replayed. A call that is already in progress when you add the webhook
  is reported with live events marked `"catch_up": true`.
- You cannot edit the webhook, use more than one URL, add custom headers, or
  select which events are sent. To change the URL or **Skip certificate
  verification**, delete the webhook and add it again.
- The secret cannot be regenerated. Deleting and adding the webhook again
  creates a new secret.
- File events report the file name in your [cloud storage](cloud-storage-integrations.html#ps3-cloud-storage-integrations). They do not include a
  download link.
- Delivery is at least once. The same event can arrive more than once, so your
  server must handle duplicates by the event `id`.

For the numeric limits, such as the event size, parallel requests, and
attempts per event, see [Limits](webhooks/webhook-delivery-and-troubleshooting.html#ps3-webhooks-limits).

---

**Set up and manage a webhook**

Add your webhook URL, copy the secret, check the delivery status, and
delete the webhook.

[Set up and manage a webhook](webhooks/set-up-and-manage-webhooks.html)

**Verify webhook requests**

Check the X-PS-Signature header so that your server accepts only
requests from phone.systems(TM).

[Verify webhook requests](webhooks/verify-webhook-requests.html)

**Webhook delivery and troubleshooting**

Understand retries, ordering, and dropped events, and fix common
delivery problems.

[Webhook delivery and troubleshooting](webhooks/webhook-delivery-and-troubleshooting.html)

**Webhook event reference**

Look up the request headers, the event envelope, and the fields of every
event type.

[Webhook event reference](webhooks/webhook-event-reference.html)