Skip to content

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