A webhook notification service is judged by its delivery contract
Signature, timeout, retries, ordering and schema. Five lines decide whether the integration survives.
3 min read
A webhook notification service is only as good as its delivery contract. Anyone can POST a JSON blob; the questions that decide whether the integration survives are what happens after a non-2xx reply, how a receiver recognises a genuine request, and whether a repeat creates a second alert.
The facts below come from AyeWatch's documentation, checked in November 2026.
The AyeWatch contract, as documented
| Property | What the documentation states |
|---|---|
| Delivery | POST to one webhook per account |
| Signature | X-AyeWatch-Signature, an HMAC-SHA256 digest of the raw body |
| Timeout | Request abandoned after 10 seconds |
| Retry | Non-2xx retried with exponential backoff up to 10 attempts |
| Ordering | Deliveries can arrive out of order |
| Schema | New fields may appear over time |
Those six lines are the whole reliability story, and they are enough to design a receiver that will not embarrass you.
Receiver rules that follow
Verify the raw body first. Compute the HMAC with your secret, compare in constant time, and reject a mismatch before parsing.
Store and acknowledge. Write the event, return 2xx, process later. A handler that calls three services inline will hit the 10 second timeout under load, and the retry will look like a duplicate.
Key on the update id. Keep it in a unique index. Two genuine events can share a headline, so deduplicate on identity, not content.
Sort on the event timestamp. Arrival order is not event order.
Where the phone fits
A webhook receiver is a server. It has no opinion about a phone. Bridging to one takes a second request to a service such as AyePing, where a bearer token and a POST to the username address are the entire credential story and a body of a title plus an optional message and label is the entire payload.
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),
message: event.content.slice(0, 2000),
label: { text: "watch", color: "blue" },
}),
});
Passing the webhook's own update id as the idempotency key closes the loop: a retry from the monitor, or a retry inside your bridge, returns the first ping instead of delivering a second.
What AyeWatch already covers
Worth stating plainly, because it saves a bridge: AyeWatch includes push and an in-app feed on every plan, and email, Slack, Discord, webhooks and API access on paid plans from $9 a month, billed in monitoring credits, after a 7 day trial. If a phone alert from the app is enough, no webhook is needed at all.
The webhook is for teams that want the event inside their own system: a CRM, a ticketing tool, a data warehouse or a custom escalation path.
Failure modes worth testing before launch
| Test | Expected behavior |
|---|---|
| Send a body with a broken signature | Receiver rejects, no parse |
| Return a 500 once | Sender retries, event not lost |
| Send the same event twice | One phone notification, one stored row |
| Delay one event by a minute | Order still resolves on timestamp |
| Send 50 events in a minute | Queue absorbs, nothing times out |
Run those five before pointing production traffic at the endpoint, and the integration will be boring, which is the goal.
Plan numbers, as of November 2026
On price, the trial tier is five pings and three tokens without a card. Hobby runs $49 for a year, presented as $4.08 a month, allowing 120,000 pings across 25 tokens. Pro costs $120 yearly, presented as $10 a month, for 1,200,000 pings and 100 tokens. Paid tiers retain a year of history.
FAQ
Do I need a public HTTPS endpoint for the webhook?
Yes. AyeWatch abandons a request after 10 seconds, so the receiver must be reachable and answer quickly over HTTPS.
Can one endpoint handle every monitor?
The documentation says each account has one webhook, and every monitor reports to it. Route on the monitor id in the payload.
What should the receiver return?
A 2xx once the event is stored. Anything else triggers a retry, which is correct for a genuine failure and wasteful for a slow handler.
FAQ
Do I need a public HTTPS endpoint for the webhook?
Yes. AyeWatch abandons a request after 10 seconds, so the receiver must be reachable and answer quickly over HTTPS.
Can one endpoint handle every monitor?
The documentation says each account has one webhook, and every monitor reports to it. Route on the monitor id in the payload.
What should the receiver return?
A 2xx once the event is stored. Anything else triggers a retry, which is correct for a genuine failure and wasteful for a slow handler.
Originally published on claudegpt.si