Test webhooks through a public tunnel
Receive Resia webhooks on your local computer through a public HTTPS URL. In this guide, you will start a receiver, open a tunnel, and send a synthetic test.
Resia → public HTTPS tunnel → local HTTP receiver
Resia cannot reach localhost on your computer or a private LAN address.
The tunnel accepts the public request and forwards it to 127.0.0.1:8000.
Before you start
- Complete Get access. Keep that terminal open, with
RESIA_API_BASEandRESIA_API_KEYset. - Use Python 3 or Node.js 18 or later. Install cloudflared or Tailscale.
- Use synthetic data only. The receiver below discards each event and must not receive customer traffic.
The synthetic test makes no Resia API request, call, or text. Your tunnel endpoint is public. The receiver checks a separate random URL token. Never use your Resia API key as that token.
1. Start the local receiver
Choose one language. Save its code to the named file.
Both examples accept notification events only and return 204.
Their 1 MiB request cap is a sample-server limit, not a Resia webhook size guarantee.
Python · receiver.py
import hmac
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer
from urllib.parse import parse_qs, urlsplit
TOKEN = os.environ["WEBHOOK_TOKEN"]
if not TOKEN:
raise SystemExit("Set WEBHOOK_TOKEN first.")
EVENT_KEYS = {
"call.ended": ("call", "id"),
"chat.ended": ("chat", "id"),
"orchestration_run.ended": ("orchestration_run", "orchestration_run_id"),
}
class Receiver(BaseHTTPRequestHandler):
def log_message(self, *args):
pass # Do not log the secret URL or request body.
def do_POST(self):
url = urlsplit(self.path)
supplied = parse_qs(url.query).get("token", [""])[0]
status = 400
if url.path != "/webhook":
status = 404
elif not hmac.compare_digest(supplied.encode(), TOKEN.encode()):
status = 401
else:
try:
length = int(self.headers.get("Content-Length", "0"))
if not 0 < length <= 1_048_576:
status = 413
else:
event = json.loads(self.rfile.read(length))
key, id_key = EVENT_KEYS[event["type"]]
if isinstance(event[key][id_key], str) and event[key][id_key]:
status = 204
print("Notification accepted; test payload discarded.", flush=True)
except (ValueError, KeyError, TypeError):
status = 400
self.send_response(status)
self.send_header("Content-Length", "0")
self.send_header("Connection", "close")
self.end_headers()
self.close_connection = True
if __name__ == "__main__":
HTTPServer(("127.0.0.1", 8000), Receiver).serve_forever()
Generate the token in the receiver terminal:
export WEBHOOK_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
python3 receiver.py &
RECEIVER_PID=$!
Node.js · receiver.mjs
import http from "node:http";
import { timingSafeEqual } from "node:crypto";
const token = process.env.WEBHOOK_TOKEN;
if (!token) throw new Error("Set WEBHOOK_TOKEN first.");
const eventKeys = {
"call.ended": ["call", "id"],
"chat.ended": ["chat", "id"],
"orchestration_run.ended": ["orchestration_run", "orchestration_run_id"],
};
function sameToken(value) {
const left = Buffer.from(value);
const right = Buffer.from(token);
return left.length === right.length && timingSafeEqual(left, right);
}
http.createServer(async (req, res) => {
const reply = (status) => {
res.writeHead(status, { "Content-Length": "0", Connection: "close" });
res.end();
};
const url = new URL(req.url, "http://127.0.0.1");
if (req.method !== "POST") return reply(405);
if (url.pathname !== "/webhook") return reply(404);
if (!sameToken(url.searchParams.get("token") ?? "")) return reply(401);
try {
const chunks = [];
let size = 0;
for await (const chunk of req) {
size += chunk.length;
if (size > 1_048_576) return reply(413);
chunks.push(chunk);
}
const event = JSON.parse(Buffer.concat(chunks).toString("utf8"));
const keys = Object.hasOwn(eventKeys, event.type) ? eventKeys[event.type] : null;
if (!keys || typeof event[keys[0]]?.[keys[1]] !== "string"
|| !event[keys[0]][keys[1]]) return reply(400);
console.log("Notification accepted; test payload discarded.");
reply(204);
} catch {
reply(400);
}
}).listen(8000, "127.0.0.1");
Generate the token in the receiver terminal:
export WEBHOOK_TOKEN="$(node -e 'console.log(require("node:crypto").randomBytes(32).toString("base64url"))')"
node receiver.mjs &
RECEIVER_PID=$!
Expected result: the server waits on 127.0.0.1:8000.
Keep this terminal open.
2. Open one public tunnel
Open a second terminal. Choose one provider.
Cloudflare Quick Tunnel · no account required
cloudflared tunnel --url http://127.0.0.1:8000
Copy the printed HTTPS URL. A Quick Tunnel needs no Cloudflare account or domain. Its URL changes when you create another tunnel. It ends when the process stops and has no uptime guarantee. Do not enable an email login prompt for this webhook endpoint. Resia cannot complete an interactive login. See Cloudflare Quick Tunnels.
Tailscale Funnel · public internet access
Sign in to Tailscale on your computer. Use a current client.
tailscale funnel --https=443 http://127.0.0.1:8000
Follow the setup prompt if Funnel is not enabled.
Funnel requires MagicDNS, HTTPS certificates, and the network's funnel permission.
A network administrator may need to authorize these settings.
Copy the printed public HTTPS URL.
Use Funnel. tailscale serve alone exposes the service only inside your private Tailscale network.
Do not use --bg for this temporary test.
Funnel uses your device's ts.net name.
Its public ports and bandwidth have provider limits.
DNS changes can take time.
See Funnel commands and requirements.
Expected result: a public HTTPS URL forwards to your local receiver. The local HTTP connection does not make the public URL HTTP.
3. Build the secret URL
Return to the receiver terminal.
It already holds WEBHOOK_TOKEN.
Do not put the token in a screenshot, shared note, or source file.
Set PUBLIC_BASE_URL to the HTTPS URL printed by your tunnel:
export PUBLIC_BASE_URL="https://YOUR-TUNNEL-HOST"
Python · build and URL-encode the token
export WEBHOOK_URL="$(python3 -c 'import os; from urllib.parse import urlencode; print(os.environ["PUBLIC_BASE_URL"].rstrip("/") + "/webhook?" + urlencode({"token": os.environ["WEBHOOK_TOKEN"]}))')"
Node.js · build and URL-encode the token
export WEBHOOK_URL="$(node --input-type=module -e 'const u = new URL("/webhook", process.env.PUBLIC_BASE_URL); u.searchParams.set("token", process.env.WEBHOOK_TOKEN); console.log(u.href);')"
Expected result: WEBHOOK_URL contains your public HTTPS endpoint and its encoded token.
Treat the entire value as a secret.
Resia webhook authentication uses this secret URL, without a signature header.
4. Send a synthetic notification
Save this existing event shape as event.json.
Its IDs and phone-free content are synthetic.
Real events contain more resource fields.
event.json · call.ended fixture
{
"type": "call.ended",
"call": {
"id": "01K1SA3F7M8QW2V5C9H4YTB0KD",
"call_agent_version_id": "01K1S9V9Q0RS7X4T2N6BJ8ZDE5",
"call_agent_id": "01K1S7RA9M8QW2V5C9H4YTB0AG",
"call_agent_name": "Front desk",
"status": "completed",
"created_at": "2026-09-15T14:00:00.000+00:00"
}
}
Post it to the tunnel:
curl --silent --show-error --output /dev/null --write-out '%{http_code}
' --header 'Content-Type: application/json' --data-binary @event.json "$WEBHOOK_URL"
Expected result: 204. The receiver prints a confirmation without the URL or payload.
Repeat the request to check that your tunnel still works.
This sample discards duplicates as well as new events; it is not a durable inbox.
API reference: call.ended.
5. Connect a test webhook and stop after use
Use the full WEBHOOK_URL in your test configuration's notification webhook field.
For example, a Call Agent uses call_ended_webhook_url.
Use the existing Quickstart when you need a real call event.
A real call or text can incur charges. The synthetic test above does not create either.
Application receivers and input requests
For an application receiver, save the event before you acknowledge it.
Deduplicate notifications by event type and resource ID within your organization.
Any 2xx acknowledges a notification; its response body does not send a reply.
| Webhook kind | Receiver response |
|---|---|
Notification: call.ended, chat.ended, orchestration_run.ended |
Any 2xx; duplicate delivery is possible. |
Input request: call.incoming, chat.incoming |
Exact 200 with valid inputs; the sample receiver above does not implement this variant. |
Input requests make one attempt. See Give an inbound agent details about the caller for its response and timeout rules.
Clear the temporary webhook URL from the test configuration before you stop the tunnel. Press Ctrl+C in the tunnel terminal. Stop the sample receiver from its original terminal:
kill "$RECEIVER_PID"
wait "$RECEIVER_PID" 2>/dev/null || true
For Funnel, check its status:
tailscale funnel status
If that mapping remains active, stop only this mapping:
tailscale funnel --https=443 http://127.0.0.1:8000 off
Expected result: your temporary receiver is no longer public. Remove the test token from the terminals when you finish.
If something fails
Status codes and connection checks
401: use the same token in the server and the encoded URL.400: check the JSON and notification type. The sample refuses input requests.404: append/webhookto the public hostname.413or a closed connection during a large upload: the body exceeds this sample receiver's 1 MiB cap.- A login page or redirect: use a direct endpoint without an interactive access gate.
- A connection error: keep both processes active. Check the local port and the provider's DNS/setup instructions.
- A failed Resia attempt: inspect request logs. Limit access because they include webhook URLs and bodies.

