To test SMS webhooks on localhost, run your handler on a local port, point a tunnel (ngrok, Cloudflare Tunnel or similar) at that port, and register the tunnel's public HTTPS URL as your webhook address. The provider then calls your laptop the same way it will call production, and you can watch real delivery reports and inbound replies land in your terminal.
The catch is that a tunnel URL is temporary and public, and an SMS webhook carries real phone numbers and message text. This guide covers the setup, a tiny receiver that records the raw request, how to replay a captured request without sending another text, and the checks that keep a dev tunnel from becoming a security hole. We make Ready, so the Ready-specific parts stick to what we can vouch for. Payload fields, event names and signature headers live in the docs, and we point you there instead of copying them.
Why localhost can't receive a webhook by itself
A webhook is an HTTP POST from the provider's servers to a URL you give them. Your laptop sits behind a router and has no public address, so the provider can't reach localhost:3000. There are three ways around that.
- A tunnel. A small agent on your machine opens an outbound connection to a relay, and the relay gives you a public HTTPS URL that forwards to your local port. This is the usual answer.
- A deployed staging server. Slower to iterate on, but it has a stable URL and no tunnel to babysit.
- No network at all. You save a real payload to a file and post it to your own handler with curl. This is what you'll use for most day-to-day work once you have a real capture.
Most developers use all three: a tunnel for the first end-to-end run, saved payloads for the edit-and-retry loop, and staging for the final check.
Step 1: build a receiver that only records
Start with a handler that does nothing except log the method, the headers and the raw body, then return a 200. You're learning what the provider actually sends, so don't parse or act on it yet. Here's a minimal Node receiver using Express:
import express from 'express';
import { appendFileSync } from 'node:fs';
const app = express();
// Keep the raw bytes. Signature checks run over these, not over parsed JSON.
app.post('/webhooks/sms', express.raw({ type: '*/*' }), (req, res) => {
const entry = {
at: new Date().toISOString(),
headers: req.headers,
body: req.body.toString('utf8'),
};
appendFileSync('captures.ndjson', JSON.stringify(entry) + '\n');
console.log('captured', req.body.length, 'bytes');
res.sendStatus(200);
});
app.listen(3000, () => console.log('listening on :3000')); Two details matter here. The handler uses express.raw, so you get the exact bytes the provider signed. And it returns a 2xx right away, which is what a real handler should do too: acknowledge fast, process from a queue. Our post on receiving SMS through inbound webhooks covers that pattern in depth.
Each capture goes to a file as one JSON line. That file becomes your fixture library in step 4.
Step 2: open a tunnel
Run the receiver, then start a tunnel against port 3000. Either of these works:
# ngrok
ngrok http 3000
# Cloudflare Tunnel, no account needed for a quick tunnel
cloudflared tunnel --url http://localhost:3000 The tool prints a public https:// address. Your webhook URL is that address plus your route, for example https://<random-name>.example-tunnel.dev/webhooks/sms. Register it in the webhook settings described in the API quickstart, which walks through a key, a first send and a webhook.
A few practical points:
- Free tunnel URLs change on every restart. When the URL changes, the old registration points at nothing. Update the webhook address each session, or use a reserved subdomain if your tunnel vendor offers one.
- Use HTTPS. The tunnel terminates TLS for you. Don't register a plain
http://address. - Keep the inspector open. ngrok ships a local web inspector, and most tunnel tools have an equivalent. It shows every request and lets you replay one with a click, which saves you from sending a fresh text for each attempt.
- Register the tunnel on a test sub-account or a staging account, never on the account your customers use. A dev URL that stays registered after you close your laptop silently drops events.
Step 3: trigger real events safely
With the tunnel up, you need events to arrive. Two kinds matter: delivery reports for texts you send, and inbound replies to your number.
For delivery reports, send a one-to-one text to a phone you own using the documented POST /v1/messages request. Always send an Idempotency-Key so a retry, within the 7 days Ready keeps it, returns the first answer instead of sending again.
curl -X POST https://api.tryready.com/v1/messages \
-H "X-API-Key: $READY_API_KEY" \
-H "Idempotency-Key: 6f1c2b8e-3d4a-4f5e-9b7c-1a2d3e4f5a6b" \
-H "Content-Type: application/json" \
-d '{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}' The number in that sample is a placeholder. Use a phone you control, and make sure the owner agreed to be texted, because a test text is still a text. You need a card on file and a number of your own, which is $2 a month, and a single-segment test text costs $0.0075 plus a $0.0045 carrier fee.
For inbound, text your Ready number from your own phone and watch the capture file. Try a normal reply, then STOP. Ready honors STOP automatically, so a send to that number is refused up front and not charged. If you want to keep testing with that phone, you'll need a different number, so plan your test phones before you start. The sandbox and test numbers guide covers how to split mock, test-key and real-phone testing.
Step 4: replay captures instead of sending more texts
Once captures.ndjson has a real delivery report and a real inbound reply, you rarely need the tunnel again. Replay the saved request against your handler. This script posts the first capture back to localhost with its original body and headers:
node -e '
const [line] = require("fs").readFileSync("captures.ndjson", "utf8").split("\n");
const { headers, body } = JSON.parse(line);
delete headers["host"]; delete headers["content-length"];
fetch("http://localhost:3000/webhooks/sms", { method: "POST", headers, body })
.then(r => console.log(r.status));
' Replaying has real advantages. It's free, it's instant, and it works offline. It's also the only practical way to test the awkward cases, because you can edit a saved body to build a duplicate, an out-of-order event or an event for a message you never sent. If your signature check is on, an edited body must fail it. That's the test you want.
Two limits to know about. A replayed capture carries its original timestamp and signature, so a handler that rejects old requests will reject your replay once it ages out. And a replay proves your code, not the provider's behavior. Run the tunnel again before any release.
Ready keeps a copy too
You don't have to capture everything yourself. Ready logs every POST it makes to your webhook, and each entry in the delivery log has the request headers and the exact signed body. Copy one into a fixture file instead of texting yourself again. An event that failed while your tunnel was down can be resent from the log once the tunnel is back, with the same body and event id. And POST /v1/webhooks/test sends a signed test event to your saved URL, which is enough to check the tunnel and your signature code before any real text.
Step 5: test the things that break in production
A handler that works with one clean event on a good day isn't tested. Use your fixtures to check these cases.
| Case | How to simulate it | What good looks like |
|---|---|---|
| Duplicate delivery | Replay the same capture twice | The second one is recognized and skipped |
| Slow handler | Add a sleep before the 200 | You see the provider retry, and you dedupe it |
| Bad signature | Edit one byte of the body | Rejected with a 4xx, logged, no side effects |
| Out-of-order events | Replay a later event, then an earlier one | State doesn't move backward |
| Handler crash | Throw before responding | The provider retries, and nothing is half-written |
| Unknown event | Add a type you've never seen | Acknowledged and stored, not a 500 |
Webhooks are at-least-once delivery, so duplicates and retries are normal, not edge cases. Store the provider's message identifier under a unique constraint and skip repeats. The same discipline applies to sending, which is why our post on idempotency keys and duplicate texts is worth reading alongside this one.
Don't treat the pipe as perfect either. Webhooks can be missed during a deploy or a laptop sleep. The delivery log shows which events your endpoint missed, and a reconciliation job that pages through GET /v1/messages with before_id catches the gaps, and you can run it in your test setup to confirm it backfills a message you deliberately dropped.
Step 6: verify signatures before you trust the tunnel
A tunnel makes a private machine publicly reachable, so anyone who learns or guesses the URL can post to it. Verification is how your handler knows a request really came from the provider.
The general pattern is the same across providers. Compute the signature over the raw body with your shared secret, compare it in constant time, and reject old timestamps if the scheme includes one. The exact header name and algorithm for Ready are in the docs, so follow those rather than a blog post. Our webhook signing guide explains the pattern in detail.
Do it from day one, in dev. Teams often leave verification off locally "to make testing easier" and then ship the same handler. A better habit is to keep the check on and test it with both a valid capture and one tampered byte. A check that has never failed in a test hasn't been shown to work.
Also treat your captures file as sensitive. It holds phone numbers and message text. Add it to .gitignore, delete it when you're done, and use *.example domains and 555-01xx numbers in any fixture you commit.
A short checklist before you leave localhost
- The handler returns a 2xx before doing real work.
- Signatures are verified over the raw body, with a failing test.
- Duplicates are skipped by message identifier.
- A reconciliation job can backfill a missed event.
- The webhook address points at a stable staging or production URL, not a tunnel.
- The tunnel is closed and the dev URL is removed from the webhook settings.
Webhook testing is mostly ordinary HTTP work: expose a port, record what arrives, replay it until your handler is boring. The SMS-specific part is respecting that every test event involves a real person's phone number. If you're building your first integration, the SMS API integration guide covers the whole build, and you can start texting to try a real send and a real webhook.