Webhooks & Real-Time Events
Receive instant HTTP callbacks when calls arrive or SMS messages land on your virtual numbers. Build automations, trigger AI agents, and integrate with any backend in real time.
How PBXme Webhooks Work
When an event occurs on your virtual number — an inbound call arrives, a call is answered, or an SMS is received — PBXme sends an HTTP POST request to a URL you specify. Your server receives the event payload, processes it, and responds with HTTP 200. No polling, no delay.
This is the mechanism that powers AI voice agent integrations: the webhook delivers the call to your AI system’s endpoint the moment a caller dials your number.
Event Reference
PBXme fires the following webhook events. Configure the destination URL per number via the dashboard or the DID Forward Setting API.
| Event | Trigger | Key payload fields |
|---|---|---|
| incoming_call | An inbound call arrives on your virtual number | did_number, caller_id, timestamp |
| call_answered | The call is picked up at the forwarding destination | did_number, caller_id, destination, timestamp |
| call_ended | A call on this number terminates | did_number, caller_id, duration_sec, timestamp |
| sms_received | An inbound SMS arrives on an SMS-enabled number | from, to, message, timestamp |
Payload Examples & Webhook Handler
Sample payloads sent by PBXme and an Express.js handler that processes both call and SMS events:
Incoming call payload (HTTP POST body):
{
"event": "incoming_call",
"did_number": "+447911123456",
"caller_id": "+19175550100",
"timestamp": "2024-11-15T14:32:00Z"
}Inbound SMS payload (HTTP POST body):
{
"event": "sms_received",
"from": "+19175550100",
"to": "+447911123456",
"message": "Hello, is this line active?",
"timestamp": "2024-11-15T14:33:12Z"
}Express.js webhook handler — handles both calls and SMS:
// npm install express const express = require("express"); const app = express(); app.use(express.json()); app.use(express.urlencoded({ extended: true })); app.post("/pbxme/webhook", (req, res) => { const payload = req.body; switch (payload.event) { case "incoming_call": console.log(`📞 Inbound call on ${payload.did_number} from ${payload.caller_id}`); // → Route to AI agent, trigger IVR, log to CRM, etc. break; case "call_ended": console.log(`📴 Call ended. Duration: ${payload.duration_sec}s`); // → Update billing records, trigger follow-up automation break; case "sms_received": console.log(`✉️ SMS from ${payload.from}: "${payload.message}"`); // → Forward to support desk, trigger auto-reply, log to CRM break; default: console.log("Unknown event:", payload.event); } // Always respond 200 to acknowledge receipt res.status(200).send("OK"); }); app.listen(3000, () => console.log("Webhook listening on port 3000"));
FAQ — Webhooks