Call Webhooks#

Call webhooks send phone.systems™ 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 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™ 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.

  • 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™ 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 results, tags and notes, and lost call resolution. For when each event is sent, see 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™
   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™ retries the request. Events of the same call are delivered in order. For details, see Webhook delivery and troubleshooting.

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. 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.

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
Verify webhook requests

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

Verify webhook requests
Webhook delivery and troubleshooting

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

Webhook delivery and troubleshooting
Webhook event reference

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

Webhook event reference