Guides

Webhooks

PressOne notifies your server about calls by requesting URLs you configure (the voice URL on a number, the action URL on a verb such as <Gather>, or a status callback URL on an outbound call). This guide covers the request format common to all of them, and how to verify that a request genuinely came from PressOne.

Standard parameters

Every webhook and action request includes the following parameters, in addition to any parameters specific to that request:

Parameter	Description
`CallSid`	Unique identifier for the call.
`AccountSid`	Your account SID.
`From`	The number that placed the call.
`To`	The number the call was placed to.
`Caller`	Mirrors `From`, retained for compatibility with existing client libraries.
`Called`	Mirrors `To`, retained for compatibility with existing client libraries.
`CallStatus`	State of the call when the request was sent. Voice URL and action requests always send `in-progress`, since the call is already answered by the time PressOne requests further instructions. Status callbacks use a wider range of values. See status callbacks.
`Direction`	`inbound` for a call received on one of your numbers, `outbound-api` for a call created through the REST API.
`ApiVersion`	The API version in effect for the call. Currently always `2010-04-01`.

Transport

By default, PressOne sends parameters as an application/x-www-form-urlencoded request body over POST. Set the relevant method or Method field to GET to receive parameters as query string parameters instead.

Requests identify themselves with a User-Agent header of TwilioProxy/1.1 (the value is kept for compatibility with tooling that filters on that string).

PressOne waits at most 10 seconds for your server to respond, and follows at most 5 HTTP redirects before treating the request as failed.

Verify webhook signatures

Every request includes an X-Twilio-Signature header (the header name is kept for compatibility with existing signature-verification libraries). Validate it before trusting the request body: anyone who knows one of your webhook URLs can otherwise send a request that looks legitimate.

The signature is computed as follows:

Start with the request URL as PressOne signed it: for a GET request, this is the full URL including its query string; for a POST request, this is the URL without a query string.
For a POST request, sort the form parameter keys alphabetically, then append each key immediately followed by its value to the URL string from step 1. Skip this step for a GET request: the query string already carries the parameters, so nothing further is appended.
Compute an HMAC-SHA1 of the resulting string, using your auth token as the key.
Base64-encode the digest. This is the expected signature.

Compare the expected signature to the X-Twilio-Signature header using a constant-time comparison, and reject the request with 403 if they do not match.

Note: For a GET request, sign the full request URL, including its query string, and pass an empty parameter object to verifySignature or verify_signature: the query string is already part of the signed URL, so no parameters get appended.

Action parameters by verb

Beyond the standard parameters, each verb's action request carries the fields that verb collected. These are documented in full on each verb's page:

Verb	Parameter	Description
Gather	`Digits`	DTMF digits collected.
Gather	`SpeechResult`	Transcribed speech text.
Gather	`Confidence`	Confidence score for `SpeechResult`.
Record	`RecordingSid`	Unique identifier for the recording.
Record	`RecordingUrl`	Public URL of the recorded audio file.
Record	`RecordingDuration`	Duration of the recording, in seconds.
Dial	`DialCallStatus`	Outcome of the dialed call.
Dial	`DialCallDuration`	Duration of the bridged call, in seconds. Present only when the call bridged.
Dial	`DialCallSid`	Unique identifier for the dialed call leg. Present only when the call bridged.

Next steps

Receiving calls: configure a voice URL and answer inbound calls.
Status callbacks: get notified as an outbound call moves through its lifecycle.
OneML overview: every verb available for scripting a call.

Last modified on July 2, 2026

Receiving calls Status callbacks

Standard parameters

Every webhook and action request includes the following parameters, in addition to any parameters specific to that request:

Parameter

Description

CallSid

Unique identifier for the call.

AccountSid

Your account SID.

From

The number that placed the call.

To

The number the call was placed to.

Caller

Mirrors From, retained for compatibility with existing client libraries.

Called

Mirrors To, retained for compatibility with existing client libraries.

CallStatus

State of the call when the request was sent. Voice URL and action requests always send in-progress, since the call is already answered by the time PressOne requests further instructions. Status callbacks use a wider range of values. See status callbacks.

Direction

inbound for a call received on one of your numbers, outbound-api for a call created through the REST API.

ApiVersion

The API version in effect for the call. Currently always 2010-04-01.

Transport

Requests identify themselves with a User-Agent header of TwilioProxy/1.1 (the value is kept for compatibility with tooling that filters on that string).

PressOne waits at most 10 seconds for your server to respond, and follows at most 5 HTTP redirects before treating the request as failed.

Verify webhook signatures

The signature is computed as follows:

Start with the request URL as PressOne signed it: for a GET request, this is the full URL including its query string; for a POST request, this is the URL without a query string.

For a POST request, sort the form parameter keys alphabetically, then append each key immediately followed by its value to the URL string from step 1. Skip this step for a GET request: the query string already carries the parameters, so nothing further is appended.

Compute an HMAC-SHA1 of the resulting string, using your auth token as the key.

Base64-encode the digest. This is the expected signature.

Compare the expected signature to the X-Twilio-Signature header using a constant-time comparison, and reject the request with 403 if they do not match.

const crypto = require("crypto");
const express = require("express");

const AUTH_TOKEN = "AUTH_TOKEN";

function verifySignature(authToken, url, params, signature) {
  let data = url;

  for (const key of Object.keys(params).sort()) {
    data += key + params[key];
  }

  const expected = crypto
    .createHmac("sha1", authToken)
    .update(data, "utf8")
    .digest("base64");

  const expectedBuffer = Buffer.from(expected);
  const signatureBuffer = Buffer.from(signature || "");

  return (
    expectedBuffer.length === signatureBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, signatureBuffer)
  );
}

const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/voice/incoming", (req, res) => {
  const signature = req.header("X-Twilio-Signature");
  const url = "https://example.com/voice/incoming";

  if (!verifySignature(AUTH_TOKEN, url, req.body, signature)) {
    return res.status(403).send("Signature verification failed");
  }

  const oneml = `<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Request verified.</Say>
  <Hangup/>
</Response>`;

  res.type("text/xml").send(oneml);
});

app.listen(3000);

Note: For a GET request, sign the full request URL, including its query string, and pass an empty parameter object to verifySignature or verify_signature: the query string is already part of the signed URL, so no parameters get appended.

Action parameters by verb

Beyond the standard parameters, each verb's action request carries the fields that verb collected. These are documented in full on each verb's page:

Verb

Parameter

Description

Gather

Digits

DTMF digits collected.

Gather

SpeechResult

Transcribed speech text.

Gather

Confidence

Confidence score for SpeechResult.