Test Plivo SMS webhooks locally

Start your appCopy Anchor Link

Install the plivo package. It includes the signature helper.

npm install plivo

Plivo sends an incoming SMS as a POST with a form-encoded body (application/x-www-form-urlencoded). The body has From, To and Text. Plivo signs the request in the X-Plivo-Signature-V2 header. It also sends X-Plivo-Signature-V2-Nonce. The signature is an HMAC-SHA256 of the URL plus the nonce, keyed with your Auth Token. It doesn't cover the body.

validateSignature needs the URL Plivo called. Set it in an environment variable, so it is the Horizon URL and not localhost.

import { validateSignature } from "plivo";

export async function POST(request: Request) {
  const authToken = process.env.PLIVO_AUTH_TOKEN;
  const webhookUrl = process.env.PLIVO_WEBHOOK_URL;
  if (!authToken || !webhookUrl) {
    return new Response("Missing PLIVO_AUTH_TOKEN or PLIVO_WEBHOOK_URL", { status: 500 });
  }

  const signature = request.headers.get("x-plivo-signature-v2") ?? "";
  const nonce = request.headers.get("x-plivo-signature-v2-nonce") ?? "";

  if (!validateSignature(webhookUrl, nonce, signature, authToken)) {
    return new Response("Invalid signature", { status: 403 });
  }

  const form = new URLSearchParams(await request.text());
  console.log(`Message from ${form.get("From")} to ${form.get("To")}: ${form.get("Text")}`);

  return new Response("Message received", { status: 200 });
}

Find your Auth Token in the Plivo console. Add both variables to .env.local:

PLIVO_AUTH_TOKEN=replace-with-your-auth-token
PLIVO_WEBHOOK_URL=https://my-app.hrzn.run/api/webhooks/plivo

Start the app.

npm run dev

Start a tunnelCopy Anchor Link

In a second terminal, open a tunnel on a subdomain you reserved.

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

Your public URL is https://my-app.hrzn.run. Keep this terminal open.

Use -s. Without it, the subdomain is random and changes every run, so your Plivo Message URL would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

Set the Message URL in PlivoCopy Anchor Link

Plivo calls the Message URL of the application assigned to your number.

1. In the Plivo console, go to Messaging, then Applications.
2. Select Add New Application.
3. Enter a name, for example Receive SMS.
4. Set Message URL to https://my-app.hrzn.run/api/webhooks/plivo and the method to POST.
5. Select Create Application.
6. Open the Numbers page and select your phone number.
7. Set Application Type to XML Application.
8. In the Plivo Application dropdown, select the application you created.
9. Select Update Number.

Send a test messageCopy Anchor Link

Plivo has no resend button for incoming messages. Text your Plivo number from your phone.