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 (via SWML).

During development, you can use localhost tunneling applications like ngrok to test your webhook handlers running on your development machine..

To learn how to use ngrok for local testing, visit the ngrok quickstart guide.

Status callbacks to keep track of events

You can configure SignalWire to send status callbacks to your webhook handler when certain events occur. The setting for webhooks can be found in the Phone Number Settings page in the SignalWire Dashboard, and they are assigned per phone number.

You can also set status callback URLs programmatically when creating a resource or a phone number from the API.

Handle events with SWML

You can configure a phone number to handle incoming calls by using a SWML script. SWML is a JSON or YAML format that tells SignalWire how to handle a phone call. You can return SWML from your webhook handler to SignalWire to handle the call.

Configure webhooks for phone numbers

To access the number settings and configure the webhooks in the SignalWire Space, click on Phone Numbers and find the number to set up.

Click on the phone number to be set up and then click to Edit Settings. In phone number settings you can set webhooks to handle events with SWML, or cXML. You can also set status callback URLs for events.

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
});

This ensures that if a malicious third party tries to spoof a webhook request, it will be rejected.