3CX Webhook documentation

The Webhook generator in 3CX WebAPI sends 3CX call events to your system in real time: ringing, answered, missed and outgoing calls, call recordings and AI transcriptions.

To try it, open the free service webhook.site and copy your unique URL. Set it as WEBHOOK_URL in the TCXWebAPI.ini file, restart the WebAPI service and make a test call.

Contents: POST scheme · Incoming answered call · Incoming missed call · Outgoing answered call · Outgoing unanswered call · Legacy GET scheme

See also: 3CX WebAPI documentation · FAQ · Changelog

POST scheme (recommended)

Set these parameters in the [Webhooks] section of the TCXWebAPI.ini file, then restart the WebAPI service:

POST = 1: send webhooks as POST requests with a JSON body (recommended). 0: legacy GET scheme
WEBHOOK_URL: main endpoint for call events
WEBHOOK_URL_2: second endpoint for events of the extensions listed in Users.csv
RECORDING_FULL_INFO = 1: send the full call details together with the recording link in the final request
WEBHOOK_POST_URL: endpoint for requests with call recordings
WEBHOOK_POST_URL_2: endpoint for recording requests of the extensions listed in Users.csv
WEBHOOK_URL_MONITOR and WEBHOOK_POST_URL_MONITOR: mirror (shadow) endpoints that receive a copy of the same requests

After the restart, WebAPI sends a webhook as each call event happens. Events of one call share the same chid.

Incoming answered call: events in order

Ringing call in IVR 809

{
    "event": "ringing",
    "callerid": "381629759787",
    "user": "809",
    "usertype": "other",
    "did": "DID Serbia 021 3220 030",
    "id": "250910183903_6-0",
    "chid": "00000000-01dc-2271-6ab7-1e2e00000006",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "804abf4a-0907-123f-b7b6-005056be101b;to-tag=e75c4562;from-tag=tSvmm0DjBt0Sg",
    "call_id2": ""
}

Ringing call in Queue 812

{
    "event": "ringing",
    "callerid": "381629759787",
    "user": "812",
    "usertype": "other",
    "did": "DID Serbia 021 3220 030",
    "id": "250910183903_6-0",
    "chid": "00000000-01dc-2271-6ab7-1e2e00000006",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "804abf4a-0907-123f-b7b6-005056be101b;to-tag=e75c4562;from-tag=tSvmm0DjBt0Sg",
    "call_id2": "YTHrJHZLJTcW88bVJ_-Deg..;from-tag=3109c954;to-tag=3d275534"
}

Ringing call to Extension 104

{
    "event": "ringing",
    "callerid": "381629759787",
    "user": "104",
    "usertype": "ext",
    "did": "DID Serbia 021 3220 030",
    "id": "250910183903_6-0",
    "chid": "00000000-01dc-2271-6ab7-1e2e00000006",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "804abf4a-0907-123f-b7b6-005056be101b;to-tag=e75c4562;from-tag=tSvmm0DjBt0Sg",
    "call_id2": "YTHrJHZLJTcW88bVJ_-Deg..;from-tag=3109c954;to-tag=3d275534"
}

Picking up the phone on extension 104

{
    "callerid": "381629759787",
    "event": "pickupincoming",
    "user": "104",
    "did": "DID Serbia 021 3220 030",
    "trtype": "NotDef",
    "id": "250910183903_6-1",
    "chid": "00000000-01dc-2271-6ab7-1e2e00000006",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "804abf4a-0907-123f-b7b6-005056be101b;to-tag=e75c4562;from-tag=tSvmm0DjBt0Sg",
    "call_id2": "EosFgS-6no_UhSZ-XrRovg..;from-tag=c820107b;to-tag=oJUZnqzFlg3LcKLD0W2aVtbx7xC33eh6"
}

Successful incoming call with a link to the conversation recording

Sent when the call ends. With MP3 compression enabled, FILES contains links to the MP3 recordings.

{
    "FILES": [
        "https://{3CXFQDN}/webapi/recording/250910183903_6-1-1.mp3"
    ],
    "event": "incoming",
    "callerid": "381629759787",
    "user": "104",
    "finishtype": "Ok",
    "transfer": "False",
    "breakside": "Internal",
    "did": "DID Serbia 021 3220 030",
    "title": "DID Serbia 021 3220 030:Answered call from 381629759787 (0:18)",
    "id": "250910183903_6-1",
    "chid": "00000000-01dc-2271-6ab7-1e2e00000006",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "804abf4a-0907-123f-b7b6-005056be101b;to-tag=e75c4562;from-tag=tSvmm0DjBt0Sg",
    "call_id2": "YTHrJHZLJTcW88bVJ_-Deg..;from-tag=3109c954;to-tag=3d275534",
    "termination_reason_details": "completed_elsewhere",
    "source_presentation": "Smith, John:DID Serbia 021 3220 030:Group1"
}

AI transcription of an incoming call

Sent separately, after the AI transcription is ready. Match it to the call by id.

{
    "event": "ai",
    "id": "250910183903_6-1",
    "summary": "An agreement on the next meeting",
    "transcription": "Hello, how are you, colleagues? Okay, I will send you a short brief of our meeting. Okay, let's meet tomorrow again. See you later, colleagues. Bye."
}

Incoming missed call: examples

Missed call in IVR 809

{
    "event": "incoming",
    "callerid": "381629759787",
    "user": "809",
    "finishtype": "Missed",
    "transfer": "False",
    "breakside": "Undef",
    "did": "DID Serbia 021 3220 030",
    "title": "DID Serbia 021 3220 030:Missed call  by IVR 809 from 381629759787",
    "id": "250910191525_7-0",
    "chid": "00000000-01dc-2276-7f8f-bc6100000007",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "9520c5c1-090c-123f-b7b6-005056be101b;to-tag=b2467f1d;from-tag=m0B6HaU0KmtrF",
    "call_id2": "xoz4awpui8Uxvgzxr3uJ6w..;from-tag=8a64207c;to-tag=3c39467d",
    "termination_reason_details": "by_did",
    "source_presentation": "Smith, John:DID Serbia 021 3220 030"
}

Missed call in Queue 812

{
    "event": "incoming",
    "callerid": "381629759787",
    "user": "812",
    "finishtype": "Missed",
    "transfer": "False",
    "breakside": "Undef",
    "did": "DID Serbia 021 3220 030",
    "title": "DID Serbia 021 3220 030:Missed call  from 381629759787",
    "id": "250910191612_8-0",
    "chid": "00000000-01dc-2276-9b59-681a00000008",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "b0e9d68e-090c-123f-b7b6-005056be101b;to-tag=ca671732;from-tag=jF2D7NmaXZp9a",
    "call_id2": "r80GE7A6HhqLoLHocKJAQQ..;from-tag=7f3b3267;to-tag=08704141",
    "termination_reason_details": "terminated_by_originator",
    "source_presentation": "Smith, John:DID Serbia 021 3220 030:Group1"
}

Missed call by extension 104 in case of busy

{
    "event": "incoming",
    "callerid": "381629759787",
    "user": "104",
    "finishtype": "Missed",
    "transfer": "False",
    "breakside": "Undef",
    "did": "DID Serbia 021 3220 030",
    "title": "DID Serbia 021 3220 030:Missed call  from 381629759787",
    "id": "250910191717_9-1",
    "chid": "00000000-01dc-2276-c224-038300000009",
    "inbound_did": "381213220030",
    "sip_displayname": "381629759787",
    "phonebook": "Smith, John",
    "call_id1": "d7b4d704-090c-123f-b7b6-005056be101b;to-tag=a17b6403;from-tag=39rcy3DQFmtXj",
    "call_id2": "FzVDAWtVxMzJ2VvTN5fW0A..;from-tag=6a484030;to-tag=3f623e63",
    "termination_reason_details": "busy",
    "source_presentation": "Smith, John:DID Serbia 021 3220 030"
}

Outgoing answered call: events in order

Outgoing call attempt

{
    "event": "dialing",
    "callerid": "381629759787",
    "user": "104",
    "id": "250910182505_3-0",
    "chid": "00000000-01dc-226f-773a-c3b300000003",
    "phonebook": "",
    "call_id1": "mu581CPivhhyi5R1nbsEfRZx6HiVY-4x;to-tag=5158a914;from-tag=ISuH9b0KHZdb0nFmc1Xq-TC-Py4NjqvE",
    "call_id2": ""
}

Picking up the handset on an outgoing call

{
    "callerid": "381629759787",
    "event": "pickupoutgoing",
    "user": "104",
    "did": "",
    "trtype": "NotDef",
    "id": "250910182505_3-1",
    "chid": "00000000-01dc-226f-773a-c3b300000003",
    "inbound_did": "",
    "sip_displayname": "",
    "phonebook": "",
    "call_id1": "mu581CPivhhyi5R1nbsEfRZx6HiVY-4x;to-tag=5158a914;from-tag=ISuH9b0KHZdb0nFmc1Xq-TC-Py4NjqvE",
    "call_id2": "M5hA4x1n5WnZt7obHxRohg..;from-tag=ac35583e;to-tag=as22301e9d"
}

Successful outgoing call with a link to the conversation recording

Sent when the call ends. With MP3 compression enabled, FILES contains links to the MP3 recordings.

{
    "FILES": [
        "https://{3CXFQDN}/webapi/recording/250910182505_3-1-1.mp3"
    ],
    "event": "outgoing",
    "callerid": "381629759787",
    "user": "104",
    "finishtype": "Ok",
    "transfer": "False",
    "breakside": "Internal",
    "did": "",
    "title": "Successful call to 381629759787 (1:53)",
    "id": "250910182505_3-1",
    "chid": "00000000-01dc-226f-773a-c3b300000003",
    "inbound_did": "381629759787",
    "sip_displayname": "",
    "phonebook": "",
    "call_id1": "mu581CPivhhyi5R1nbsEfRZx6HiVY-4x;to-tag=5158a914;from-tag=ISuH9b0KHZdb0nFmc1Xq-TC-Py4NjqvE",
    "call_id2": "M5hA4x1n5WnZt7obHxRohg..;from-tag=ac35583e;to-tag=as22301e9d",
    "termination_reason_details": "polling",
    "source_presentation": "381213220030"
}

AI transcription of an outgoing call

Sent separately, after the AI transcription is ready. Match it to the call by id.

{
    "event": "ai",
    "id": "250910182505_3-1",
    "summary": "The customer reported a lost debit card and requested immediate blocking, which the agent confirmed was done right away. A replacement card was ordered to be delivered within 3–5 business days, with mobile app access available in the meantime. The call concluded positively, with the customer expressing gratitude and the agent offering well-wishes.",
    "transcription": "Hello, I just realized I lost my debit card, and I need to block it right away. Oh, I’m sorry to hear that. Don’t worry, we’ll take care of it right now. Could you please confirm your full name and date of birth for security? Sure. My name is John Peterson, and my date of birth is March 12, 1990. Thank you, Mr. Peterson. I’ve verified your details. I’ll go ahead and block your current card so it can’t be used anymore. This will take effect instantly. Perfect, thank you so much. That’s a relief. You’re welcome. Now, would you like me to order a replacement card for you? We can deliver it to your registered address within three to five business days. Yes, please. That would be great. Done. I’ve placed the order. You’ll also receive a text message with tracking information once it’s dispatched. In the meantime, you can continue using our mobile app for transfers and payments. That’s very convenient. Thanks for helping me so quickly. My pleasure, Mr. Peterson. Is there anything else I can do for you today? No, that’s everything. I really appreciate your support. Anytime. Thank you for calling, and we wish you a great rest of your day. You too. Goodbye.",
    "sentiment_score": "5"
}

Outgoing unanswered call: events in order

Outgoing call attempt

{
    "event": "dialing",
    "callerid": "381629759787",
    "user": "104",
    "id": "250910180942_2-0",
    "chid": "00000000-01dc-226d-5102-741100000002",
    "phonebook": "",
    "call_id1": "9QkKqbI9DI0SpjQZXNSZdv.ua1JW-k.y;to-tag=f40b0d76;from-tag=DIHYo1dRIJC0HVTa9-6nYd4EuXwHcxuY",
    "call_id2": ""
}

Unanswered outgoing call

{
    "event": "outgoing",
    "callerid": "381629759787",
    "user": "800",
    "finishtype": "Missed",
    "transfer": "False",
    "breakside": "Undef",
    "did": "",
    "title": "Unanswered call to 381629759787",
    "id": "250910180621_1-0",
    "chid": "00000000-01dc-226c-d961-c78c00000001",
    "inbound_did": "",
    "sip_displayname": "",
    "phonebook": "",
    "call_id1": "wOT6uo3_pW5puFEMBSqMmw..;to-tag=5d14ed24;from-tag=0c2fb431",
    "call_id2": "oTbiMZoH2j7v-RGIQomkPw..;from-tag=a2260f2b;to-tag=8b30d901",
    "termination_reason_details": "declined",
    "source_presentation": "381213220030"
}

Screenshots

Legacy GET scheme

Use the POST scheme for new integrations. The GET scheme sends the same call events with the fields in URL parameters.