Webhooks

Webhooks are HTTP requests sent to your server from SignalWire when an event occurs. They help receive information about events like inbound calls to your phone numbers, or messages.

In addition to getting information about events, some webhooks also allow you to tell SignalWire how an event should be handled.

During development, you can use localhost tunneling applications like ngrok to test your webhook handlers locally. See the ngrok quickstart guide to get started.

Configure webhooks for phone numbers

To handle an inbound call or message, you point your phone number at a Resource that holds your webhook URL. When an event arrives, SignalWire requests that URL and your server responds with SWML, the SignalWire Markup Language that tells SignalWire how to handle the call.

Status callbacks to keep track of events

Status callbacks are asynchronous HTTP requests SignalWire sends to your server as a call, message, or recording moves through its lifecycle, keeping your application informed of each state change.

You subscribe to a status callback programmatically: when you create the call or message, provide a callback URL on the relevant SWML method, and SignalWire posts to it each time the state changes. What you set and the states you receive depend on what you’re tracking:

Status callbacks are advisory

Status callbacks are best-effort notifications, not a reliable realtime signal. They are delivered asynchronously over HTTP, so a callback can arrive late, arrive after a retry, or not arrive at all — if your server is unreachable when SignalWire sends the request, the callback is simply lost, and nothing notifies your application that it was missed. Because a missed callback is invisible to the receiver, never gate time-critical or business-critical actions (billing, compliance steps, call teardown, failover) solely on receiving one.

For critical paths, use a mechanism whose failure modes are visible to your application:

• RELAY over WebSocket (also for TypeScript) — events arrive over a persistent connection, so your client knows immediately when it is disconnected and can fail safe. See the RELAY events reference for Python and TypeScript.
• REST polling and reconciliation — treat a callback as a hint: confirm the state with a GET before acting, and run a periodic sweep to catch missed callbacks. Use Retrieve a call and Retrieve a message on the Compatibility API, or voice logs and message logs on the SignalWire REST API.
• In-call flow logic — act on results inside the call flow instead of out-of-band. SWML’s connect sets result variables (connect_result) you can branch on, and cXML’s <Dial> action URL receives the dial outcome as part of document execution.

Verify webhook signature

To verify webhooks that originated from SignalWire, SignalWire signs its requests with a digital HMAC security key. You can verify that the security key matches the key documented in your Dashboard’s API Credentials with the validateRequest method.

1
import { validateRequest } from "@signalwire/js";
2
3
// prepare raw body for validation
4
app.use(express.json({
5
  verify: (req: any, _res, buf) => {
6
    req.rawBody = buf.toString();
7
  }
8
}));
9
10
app.post("/mywebhook", (req: any, res) => {
11
  const valid = validateRequest(
12
    "<SIGNING_KEY_FROM_Dashboard>",
13
    req.headers["x-signalwire-signature"] as string,
14
    "https://example.ngrok.io/mywebhook", //this should be the public-facing URL of your webhook handler
15
    req.rawBody
16
  );
17
18
  if (!valid) return res.status(401).send("Invalid signature");
19
20
  res.sendStatus(200);
21
});