Subscribe to phone call events

Posting a request to this endpoint will create a new webhook subscription to the specified event.

List of accepted events

Any of these events can be specified as a query parameter in the invocation URL.

info

Check out some of the payload examples.

💡 You can also subscribe and unsubscribe to events manually. Learn more here.

📋 You can also list all webhooks and delete subscriptions using the API.

Event	Description
call.status.update	Triggers when a phone call status changes (e.g., ringing, answered, ended). Example.
call.incoming.completed	Triggers when an incoming phone call is completed (answered or missed). Example.
call.outbound.completed	Triggers when an outbound phone call is completed (answered or failed). Example.

tip

Subscribe to call.status.update when you need to learn about every call state transition happening on any direction, or to call.incoming.completed or call.outbound.completed when you only need to know when the call has ended.

Parameters

info

These parameters should be sent as JSON payload in the request body.

Field	Description
hook_url	A valid and publicly reachable URL that 2Chat will invoke when the event is triggered.
channel_uuid	The UUID of the virtual phone number where the event will be received. You can get the UUIDs of your numbers here.

Invocation

Assume we want to subscribe to the event call.status.update as example:

cURL

curl --location --request POST 'https://api.p.2chat.io/open/webhooks/subscribe/call.status.update' \
--header 'X-User-API-Key: your_api_key_here' \
--header 'Content-Type: application/json' \
--data-raw '{
    "hook_url": "https://webhook.com/3a09f244-ad9f-42f8-8230-1d75ec5f9618",
    "channel_uuid": "DID1a42d563-e0a7-4b14-b9e6-ee49e61af123"
}'

Python

import requests
import json

url = "https://api.p.2chat.io/open/webhooks/subscribe/call.status.update"

payload = json.dumps({
  "hook_url": "https://webhook.com/3a09f244-ad9f-42f8-8230-1d75ec5f9618",
  "channel_uuid": "DID1a42d563-e0a7-4b14-b9e6-ee49e61af123"
})
headers = {
  'X-User-API-Key': 'your_api_key_here',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

JavaScript

var axios = require('axios');
var data = JSON.stringify({
  "hook_url": "https://webhook.com/3a09f244-ad9f-42f8-8230-1d75ec5f9618",
  "channel_uuid": "DID1a42d563-e0a7-4b14-b9e6-ee49e61af123"
});

var config = {
  method: 'post',
maxBodyLength: Infinity,
  url: 'https://api.p.2chat.io/open/webhooks/subscribe/call.status.update',
  headers: { 
    'X-User-API-Key': 'your_api_key_here', 
    'Content-Type': 'application/json'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Response

The API will return the newly configured webhook if successful.

{
    "success": true,
    "data": {
        "uuid": "WHK530c9d58-2259-4ce2-82a8-1941f3a60665",
        "event_name": "call.status.update",
        "channel_uuid": "DID1a42d563-e0a7-4b14-b9e6-ee49e61af123",
        "hook_url": "https://webhook.com/3a09f244-ad9f-42f8-8230-1d75ec5f9618",
        "created_at": "2025-09-18T01:58:02Z"
    }
}

Field	Description	Example values
uuid	The unique identifier of the webhook that you will need to make changes to it	WHK530c9d58-2259-4ce2-82a8-1941f3a60665
event_name	The name of the event this webhook is subscribed to	call.status.update
channel_uuid	The unique UUID of the channel this webhook is subscribed to	DID1a42d563-e0a7-4b14-b9e6-ee49e61af123
hook_url	The URL 2Chat will call when a event is triggered	https://webhook.com/...
created_at	UTC timestamp for when the webhook was created	2025-09-18T01:58:02Z