How webhooks work

Webhooks send an HTTP request when something changes in OnlineOrNot.

A webhook only runs when you selected both the event and the check, heartbeat, or status page that produced it.

Endpoints, events, and resources

A webhook has:

• Endpoint URL - the URL that receives an HTTP POST
• Description - an optional note about what the webhook is for
• Events - what should trigger the webhook
• Resources - which checks, heartbeats, and status pages it watches

You can reuse one webhook for several monitors. You can also attach an existing webhook while editing a check or heartbeat.

Supported events

Event	Produced when
uptime.down	A selected check goes down
uptime.up	A selected check recovers
heartbeat.down	A selected heartbeat misses its deadline
heartbeat.up	A selected heartbeat resumes reporting
status_page.incident.started	An incident starts on a selected status page
status_page.incident.updated	An active incident receives an update
status_page.incident.resolved	An incident is resolved

The event and resource must make sense together. For example, uptime.down cannot happen for a webhook connected only to a status page.

When OnlineOrNot sends a webhook

OnlineOrNot sends webhooks when a monitor changes status. It does not send a webhook after every check or heartbeat ping.

For example, a check normally follows this sequence:

Up -> Down: send uptime.down
Down -> Up: send uptime.up

Reminder alerts do not send another webhook.

Status page webhooks are sent when an incident starts, is updated, or is resolved. This includes incidents created by a person and incidents created from linked monitors.

JSON sent to your endpoint

OnlineOrNot sends JSON with Content-Type: application/json.

Uptime, heartbeat, and status page events do not all use the same JSON fields. Check the event field before reading the rest of the payload.

See the webhook payload reference for examples.

Heartbeat alerts use heartbeat.down and heartbeat.up in the event field.

Delivery behavior

OnlineOrNot changes the monitor or incident before it sends the webhook. A webhook may be missed, sent more than once, or arrive out of order.

Your endpoint should:

• return a 2xx response quickly
• process slow work separately
• safely handle the same event more than once
• use the OnlineOrNot API to confirm the current status before making an important decision

The dashboard does not currently show delivery attempts or response codes.

Authenticating deliveries

Webhook requests are not signed and cannot include your own authorization header. Use HTTPS and a hard-to-guess URL.

Before taking a sensitive action, confirm the current status through the authenticated OnlineOrNot API.

Webhooks and other notification features

Webhooks are different from:

• On-call integrations, such as PagerDuty or Opsgenie, which connect directly to those services.
• Status page subscriptions, which send public incident updates to your visitors.
• API tokens, which let your software make requests to OnlineOrNot.

To configure an endpoint, see Send alerts to webhooks. To manage webhooks with the API, see the Webhooks API reference.