WhatsApp call termination and capture webhook examples

For the exhaustive schema-derived catalog, see all examples.

What it is

Handle WhatsApp call termination, recording, and transcription events.

Before you begin

Create a public HTTPS endpoint in your application.
Configure a YCloud webhook endpoint for the event types you need.
Store the endpoint signing secret securely.
Make event processing idempotent.

How it works

YCloud sends an HTTP POST request when the event occurs. Verify the signature, durably record the event, return a 2xx response, and process slow work asynchronously.

Request

The scenarios below show requests delivered to your webhook URL. Treat the event id as the delivery identifier and use type to route the payload.

Response

Return a 2xx status after accepting the event.

HTTP/1.1 200 OK

For endpoint setup, signature validation, and retry behavior, see Configure webhooks.

Both the business or the WhatsApp user can terminate the call at any time. When either the business or the WhatsApp user terminates the call, you receive a Call Terminate webhook:

Call Completed

Request

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTE",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Call Failed

Request

{
  "id": "evt_675907f431c55113a751d0e7",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-11T03:33:08.679Z",
  "callingTerminate": {
    "id": "675907a13ae4a901f05fee95",
    "wacid": "wacid.HBgNODYxNTE1NzEzNzYyM",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "fromUserId": "ID.13491208655302741918",
    "fromParentUserId": "ID.11815799212886844830",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733826484000,
    "endTime": 1733826637000,
    "duration": 30,
    "status": "FAILED",
    "errorCode": "131000"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Route the event by type, deduplicate it by id, and move slow or failure-prone work to an asynchronous processor.

Call recording available

For an API-sourced call with recording enabled, whatsapp.call.recording.updated reports recording availability or permanent processing failure.

Request

{
  "id": "evt_call_recording_01JZ8K4V7H3P6Q9R2T5W8X1Y4Z",
  "type": "whatsapp.call.recording.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:00:00.000Z",
  "callingRecording": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0c2e4b05c2d8f1a3b47",
    "status": "AVAILABLE"
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Use callingRecording.wacid to identify the call and phoneId to identify the business phone number. Download the mediaAssetId only when status is AVAILABLE. Recording processing is separate from the call-termination result. For FAILED, inspect error.code and error.retryable. See recordings and transcriptions.

Call transcription failed

For an API-sourced call with transcription enabled, whatsapp.call.transcription.updated reports transcription availability or permanent processing failure.

Request

{
  "id": "evt_call_transcription_01JZ8K5A9C4D7E0F3G6H9J2K5M",
  "type": "whatsapp.call.transcription.updated",
  "apiVersion": "v2",
  "createTime": "2026-08-04T08:01:00.000Z",
  "callingTranscription": {
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "phoneId": "461269257068832",
    "mediaAssetId": "66b1f0d9e4b05c2d8f1a3b48",
    "status": "FAILED",
    "error": {
      "code": "CALLING_TRANSCRIPTION_PROCESSING_FAILED",
      "retryable": false
    }
  }
}

Response

Acknowledge the delivery after durably accepting the event.

HTTP/1.1 200 OK

Explanation

Read callingTranscription rather than callingRecording. In this example, status is FAILED and error.retryable is false. Do not attempt to download the failed asset. An AVAILABLE result uses mediaAssetId for download; the transcription result is separate from the recording result and call-termination status.

Getting Started

Guides

Endpoints

Webhooks

WhatsApp call termination and capture webhook examples

What it is

Before you begin

How it works

Request

Response

Call Completed

Request

Response

Explanation

Call Failed

Request

Response

Explanation

Call recording available

Request

Response

Explanation

Call transcription failed

Request

Response

Explanation

​What it is

​Before you begin

​How it works

​Request

​Response

​Call Completed

​Request

​Response

​Explanation

​Call Failed

​Request

​Response

​Explanation

​Call recording available

​Request

​Response

​Explanation

​Call transcription failed

​Request

​Response

​Explanation

What it is

Before you begin

How it works

Request

Response

Call Completed

Request

Response

Explanation

Call Failed

Request

Response

Explanation

Call recording available

Request

Response

Explanation

Call transcription failed

Request

Response

Explanation