Webhooks overview
A webhook is an HTTP request that Wipple CPaaS sends to your application. Webhooks are how the platform announces new calls, asks your application what to do next, and reports what happened. Your application answers with a JSON array of Functions, or with an empty body when no further instructions are needed.
Kinds of webhook
| Webhook | Configured on | Sent when |
|---|---|---|
| New Call (POST) / New Call (GET) | Application (call hook) | A new inbound call arrives, or an outbound call created through the REST API is answered |
| Call status hook | Application (call status hook) | The status of a call changes (ringing, in-progress, completed, ...) |
| Action hooks | Individual Functions (actionHook, dtmfHook, eventHook, ...) |
A Function finishes or produces an event; see the page of each Function for the payload |
| Client Authentication | Account (registration hook) | A SIP or WebRTC client attempts to register |
| New Client Tool Request | The agent or llm Function (toolHook) |
An AI agent invokes a client-side tool that your application implements |
Common properties
Every webhook related to a call carries the identifiers you need to correlate it with your own records:
call_sid: the unique identifier of the call leg. Use it with the REST API to update or end the call.account_sidandapplication_sid: the account and application the call belongs to.direction,from,to,caller_name: who is calling whom.call_statusandsip_status: the current state of the call and the latest SIP status code.
Action hooks add Function-specific properties, for example the collected digits or speech result of a gather Function, or the call_status and duration of the dialed leg after a dial Function.
HTTP method and URL
Hook URLs may be absolute (https://{yourserver}/menu) or relative (/menu). A relative URL is resolved against the call hook URL of the application. The default method is POST with a JSON body; if you configure a hook with GET, the same properties are sent as query parameters instead.
Authentication
If you configure a username and password on a hook, Wipple CPaaS includes an Authorization: Basic <base64(username:password)> header on every request to that hook. Your application should verify it and reject requests that do not carry valid credentials.
Responding
- Respond with HTTP
200as quickly as possible. Long-running work should be performed asynchronously. - To give the platform new instructions, return a JSON array of Functions. Any Functions still queued from the previous response are discarded and replaced.
- To let the current application continue unchanged, return an empty body or an empty array
[]. - For status-only hooks (the call status hook,
dtmfHook,eventHook, and similar), Functions in the response are ignored; a200response with an empty body is sufficient.
WebSocket alternative
Instead of HTTP, an application URL beginning with wss:// makes Wipple CPaaS open a WebSocket connection to your server and exchange the same JSON payloads as messages over that single connection. The property names and Function definitions are identical.