Webhook to phone notification: the smallest relay that stays correct
Four lines do the work: verify, slice the title, slice the message, send an idempotency key.
· 3 min read
A webhook to phone notification takes one JSON event and turns it into one buzz. The useful version is small: verify the sender, take a title and a line of detail, forward them, and make the forward safe to retry. Everything else is polish.
The smallest workable relay
export default async function handler(req, res) {
const raw = await readBody(req);
if (!verify(raw, req.headers["x-aye-watch-signature"])) {
return res.status(401).end();
}
const event = JSON.parse(raw);
await fetch("https://ayeping.com/@you", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AYEPING_TOKEN}`,
"Idempotency-Key": event.update_id,
},
body: JSON.stringify({
title: event.headline?.slice(0, 100) ?? "update",
message: event.content?.slice(0, 2000) ?? "",
}),
});
res.status(204).end();
}
Four lines do the real work: the signature check, the two slices and the idempotency key. The signature rule and payload fields come from AyeWatch's API reference, and the notification format from AyePing's docs.
Why each line exists
The signature check. Deliveries are signed, and the header holds an HMAC-SHA256 digest computed over the raw bytes with your secret. Skip it and anyone who finds the URL can make your phone buzz.
The slices. A title is 1 to 100 characters on one line, and a message is up to 2,000. A page-change payload can carry more than both, and an over-long title returns 400 invalid_body rather than being trimmed for you.
The idempotency key. Webhook senders retry, and so do HTTP clients inside your function. Sending the event's own id means a repeat returns the first ping instead of a second notification.
The three mistakes worth avoiding
| Mistake | What it causes |
|---|---|
| Parsing before verifying | Malformed or hostile JSON handled by your code |
| Doing slow work inline | 10 second timeout, then up to 10 retries |
| Deduplicating on the headline | Two different events collapse into one |
The second one is the most common. The documented timeout is 10 seconds, with exponential backoff up to 10 attempts on a non-2xx response, so the receiver should store the event and return before calling anything slow.
Mapping whatever arrives
Webhook payloads differ between senders. Write the mapping explicitly, per sender, and keep it in one place:
- title from a headline, a subject or a service plus status
- message from a body, a diff summary or an error string
- label from a severity field, if one exists
If a sender has no usable title, compose one from the fields it does have. "Pricing page changed" beats "Event received".
When you do not need a relay
If the monitor already sends push to its own app, skip the bridge. AyeWatch ships phone push and an activity feed with every subscription, and adds email, Slack, Discord, webhooks and API access once you move to a paid tier, which begins at $9 monthly in monitoring credits after a trial week. The relay earns its place when the alert must land somewhere else: a different app, a team channel or your own service.
Testing the bridge
Send a test event with a valid signature and watch the phone. Then send one with a bad signature and confirm a 401 with no notification. Then send the same id twice and confirm one buzz. Those three checks catch almost every mistake in a first version.
Costs, as of November 2026
Pricing in November 2026: five pings and three tokens come free of charge with no card, which is enough to prove the relay. Hobby costs $49 annually (or $8 month to month) for 120,000 pings and 25 tokens. Pro costs $120 annually, or $20 monthly, for 1,200,000 pings and 100 tokens. Unused volume is not banked.
FAQ
Can the webhook post directly to the phone service?
Only if the sender lets you customise the request body and headers. Most send a fixed payload, which is why the relay exists.
What if the phone service is down?
Return 2xx to the webhook once the event is stored, and retry the phone send from your own queue. Otherwise the sender retries the whole event.
Do I need a database?
For one monitor, a log file plus an in-memory set of ids is enough. Past a few thousand events, a table with a unique index on the id is simpler than cleaning up duplicates later.