Webhooks (Real-Time Events)

Overview

Webhooks allow you to receive real-time event notifications from the phone system by sending POST requests directly to your own API endpoint. This enables seamless integration with external systems—such as CRMs, databases, or custom applications—by automating workflows based on live call events, messages, and other system activity.

Note: Webhook payloads may be delivered in either JSON or URLENCODED format, depending on the specific event type or system configuration.

---

SMS / MMS Messages (JSON)

 

Setup: Call Routing → Inbound → Edit Phone Number → API/Webhooks tab

Inbound Message:

{
"eventType": "inboundMessage",
"toNumber": "{TO_NUMBER}",
"fromNumber": "{FROM_NUMBER}",
"containerID": "{CONTAINER_ID}",
"tenantID": "{TENANT_ID}",
"conversationID": "{CONVO_ID}",
"messageText": "{ESCAPED_MESSAGE_TEXT}"
}

Outbound Message:

{
"eventType": "outboundMessage",
"toNumber": "{TO_NUMBER}",
"fromNumber": "{FROM_NUMBER}",
"containerID": "{CONTAINER_ID}",
"tenantID": "{TENANT_ID}",
"conversationID": "{CONVO_ID}",
"messageText": "{ESCAPED_MESSAGE_TEXT}"
}

Explanation: Whenever an inbound text message is received from an outside number (like someone's cell phone) you will receive an inboundMessage event. The "FROM" number will be the outsider, and the "TO" number will be the number they texted that belongs to the PrimeVOX customer.

 

Conversely, whenever an outbound message is sent from a Primevox user (via our web portal, mobile/desktop apps, or SIP SIMPLE messaging), you will receive an outbound Message event, where the "FROM" number is the Primevox customer's number, and the "TO" number is the outsider.

 

For parsing MIME attachments (MMS messages), please review the documentation on SMS/MMS messaging.

---

Inbound Calls (URLENCODED body)

​

Setup: Call Routing → Inbound → Edit Phone Number → API/Webhooks tab

Inbound Call:

eventType=InboundCall&eventTarget=phoneNumber&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&didNumber={PHONE_NUMBER}&didDescription={PHONE_NUMBER_DESCRIPTION}&didGroup={GROUP_NAME}&cidPrefix={CALLERID_PREFIX}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}&callerIdName={FROM_NAME}

Hangup Call:

eventType=HangupCall&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Explanation: When a call initially comes into the phone system, even before it does anything, we will fire off an InboundCall webhook event. No matter what happens to the call, the HangupCall event will be fired whenever the call ends. If the call had been answered by a real live person (extension), then extNumber and extName will be filled with that information.

 

Outbound calls are not configured in this way and must utilize the Extensions settings in the next section.

 

 

---

Extensions + Outbound Calls (URLENCODED body)

Setup: Extensions → Manage → Edit Extension → API/Webhooks tab

Extension Ringing:

eventType=ringAttempt&eventTarget=extension&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}

Extension Answered:

eventType=ExtensionAnswered&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}&callerIdName={FROM_NAME}&extensionNumber={EXTENSION_NUMBER}&extensionName={EXTENSION_NAME}

Extension Hung Up:

eventType=inboundCallCompleted&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Voicemail Left by Caller:

eventType=voicemailHangup&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&callerIdName={FROM_NAME}&callerIdNum={FROM_NUMBER}

Outbound Call Placed Syntax: 

eventType=outboundCall&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&extNumber={EXTENSION_NUMBER}&extName={EXTENSION_NAME}&callUuid={CALL_UUID}&numberDialed={NUMBER_DIALED}

 

 

---

Ring Groups (URLENCODED body)

Setup: Call Control → Ring Groups → Edit Ring Group → API/Webhooks tab

Caller Enters Ring Group:

eventType=ringAttempt&eventTarget=ringGroup&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&rgNumber={RING_GROUP_EXTEN}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}

 

 

---

Queues (URLENCODED body)

Setup: Call Control → Queues → Edit Queue → API/Webhooks tab

Caller Enters Queue:

eventType=queueEntered&eventTarget=queue&containerId={CONTAINER_ID}&tenantId={TENANT_ID}&queueNumber={QUEUE_EXTEN}&callUuid={CALL_UUID}&callerIdNum={FROM_NUMBER}

 

 

• Related Articles

• Webhooks

  What is a Webhook? A webhook allows your phone system to send real-time data or notifications to an external application (usually your own server or a third-party platform). It acts as a trigger: when a specific event occurs—such as an incoming call, ...

• Real-Time Data (V2)

  Real-Time Queues (API Access) This API endpoint allows you to retrieve real-time data from queues within a phone system container. It is useful for monitoring active queue performance, agent activity, and call volume in real time. Endpoint Request ...

• My Phone did not update to Daylight Savings Time

  IP Phone Time Update After Daylight Savings Some models of IP phones may not automatically update their time settings after a Daylight Savings Time (DST) change. If you notice incorrect time displays on your devices, you may need to manually trigger ...

• Call Queues

  What is a Call Queue? A Call Queue holds incoming calls in a virtual waiting line and distributes them to available agents based on predefined rules. It helps manage high call volumes efficiently by ensuring callers are handled in the order they ...

• Inbound Routes (Phone Numbers)

  What is an Inbound Route? The Inbound section of the PBX is where phone numbers are entered and routed to specific features and extensions. This section can be found under the Call Routing tab. Adding a Group Before adding a phone number, you can add ...