Webhooks

A Webhook sends a Monitor’s events to your own endpoint, as signed JSON. Use one when your own code should act on an alert: open a ticket, page someone, or record the outage.

A Webhook belongs to one Monitor, and is set up on that Monitor’s Webhooks tab. It is not a Channel, so it never appears in your Notification rules. A Monitor can have up to 5 Webhooks.

Adding a Webhook

1. Open the Monitor, then its Webhooks tab.
2. Press Add webhook.
3. Enter your Endpoint URL. It must be an https address on the public internet.
4. Press Add webhook again.

The Webhook is added at once, and we send your endpoint a signed test event. The dialog then shows the signing secret, this one time, and whether your endpoint accepted the test.

A Webhook whose endpoint accepted a message is Active. Until then it is Pending, and we still send it every event. An endpoint that checks signatures refuses the test until it holds the secret: give it the secret, then choose Send test in the Webhook’s menu. The Webhook turns Active on its endpoint’s first 2xx answer.

We do not follow redirects. Give the final URL your endpoint answers on.

Choosing events

Under Advanced, every event this Monitor’s Checks can send is ticked. Untick the ones your endpoint does not need. While every event stays ticked, the Webhook also hears the events of a Check you turn on later.

To change a Webhook’s events later, choose Edit in its menu. To send to another URL, add a new Webhook and delete the old one.

A Webhook is sent each message once. It gets no Repeat alerts.

The request

Each message is a POST to your Endpoint URL, with a JSON body and these headers:

Header	What it carries
content-type	The body is JSON.
user-agent	uup-webhook/1 (+https://docs.uup.dev/webhooks/), with the address of this page.
x-uup-webhook-version	The version of the payload, 1.
x-uup-delivery	The message's id. It is the same on every attempt to send that message, and on Send again.
x-uup-webhook	Which of your Webhooks the request is for.
x-uup-event	The event the message is about, as the body's event says it. A test is about no event, so it has none.
x-uup-signature	The signature your endpoint checks the request with.

The Payload reference lists every field of the body, with examples.

The signing secret

The signing secret starts with uup_whs_. It is shown once, when you add the Webhook, so copy it then. After that the Webhook’s card shows only its last four characters.

Each request is signed with it: the signature is made from the request’s time and its exact body, so your endpoint can check that the request came from us and was not changed on the way. Verifying signatures shows how, in Node, Python, Go and PHP.

To replace the secret, press New secret on the Webhook’s card. The old secret stops working at once, so requests your endpoint checks with it fail until you give it the new one.

When your endpoint does not accept a message

Your endpoint accepts a message by answering with any 2xx status within 10 seconds.

When it answers 429 or a 5xx status, does not answer in time, or the connection fails, we try again. A message is tried up to 5 times. Between one try and the next we wait 10 seconds, 20 seconds, 40 seconds and 80 seconds, in that order: each wait is double the one before it, and never more than 15 minutes. When a 429 answer says how long to wait, we wait that long instead.

Other answers are not tried again:

• A redirect (3xx) fails. Change the Endpoint URL to the address it redirects to.
• 401, 403, 404 or 410 means the endpoint refuses the address itself. These count toward turning the Webhook off.
• A URL whose name points to a private address counts the same way. We never send to a private address.
• Any other 4xx status fails.

Send again

Under the Webhooks, Deliveries lists every message, with its payload, the request we sent and what your endpoint answered. Open a message, then press Send again to send it once more.

Send again sends the same body under the same id, signed with the current secret. When your endpoint already accepted the message, the dashboard asks first, because an endpoint that skips an id it has handled will skip this one too.

We keep what was sent for 30 days, so you can send a message again for that long. Send again does not count toward turning a Webhook off.

When a Webhook is turned off

We turn a Webhook off after 10 such failures in a row, with no accepted message between them, spread over at least 1 day. A short outage at your endpoint never turns it off, and neither does an answer that we try again.

The owner and the admins get an email when it happens. The Webhook’s card says Turned off, with the last answer your endpoint gave.

Once your endpoint is fixed, press Turn on on the card. We send a test first, and the Webhook turns on only when your endpoint accepts it.

To stop sending to an endpoint for good, choose Delete in the Webhook’s menu. Anything still waiting to be sent to it is not sent.