1. Webhooks
  2. Send alerts to webhooks

Webhooks

Send alerts to webhooks

This is a feature of Paid Plans.

Create a webhook

Go to Webhooks in the sidebar and click Add endpoint.

You'll need to provide:

  • URL - where OnlineOrNot will POST alerts
  • Events - which events should trigger the webhook (uptime.down, uptime.up, heartbeat.down, heartbeat.up, or status page incident events)
  • Resources - which uptime checks, heartbeats, or status pages should use this webhook

Select at least one resource and one event. Match each resource type to its events:

  • For status pages, select at least one status_page.incident.* event.
  • For uptime checks, select uptime.down, uptime.up, or both.
  • For heartbeats, select heartbeat.down, heartbeat.up, or both.

You can combine resource types in one webhook, but include matching events for all selected types. Remove events for resource types you haven't selected. When editing via the API, change events and resources together in the same PATCH request if you're switching resource types.

Once created, the webhook will fire whenever the selected events occur on the selected resources.

Keep credentials out of saved webhook URLs

  1. Open Environment variables for your organization. Save the full webhook URL as a secret named WEBHOOK_URL, or save just the credential as a secret named TOKEN. Use secret rather than config for credentials.
  2. Create or edit a webhook and enter the reference in Endpoint URL:
    • Whole URL: {{WEBHOOK_URL}}
    • Embedded credential: https://example.com/{{TOKEN}}
    • Literal URL without references: https://example.com/hooks
  3. Select events and resources, then click Add endpoint or Update endpoint.
  4. Reopen the webhook to check the saved template. The dashboard and API return exactly what you saved, never the expanded URL or secret value.

Use case-sensitive variable names from the same organization. Existing secret and config variables can both be referenced; creating or replacing them requires variable-management permissions. A webhook editor can reference an existing variable without permission to read it.

Encode path and query values before saving the variable when needed. Substitution happens once, as-is, without automatic URL encoding or expanding references inside a variable value. Use {{{{TOKEN}}}} to send literal {{TOKEN}} text. Template destinations must resolve to a public HTTPS endpoint without credentials in the username/password, fragments, or redirects; use the final endpoint URL. An invalid resolved destination fails at delivery, not in a secret preview.

Only give webhook editing access to trusted people: an editor can send an existing secret to an endpoint they control. Write-only secret reads protect responses, not against this exfiltration risk. If a credential was previously saved in a literal URL, rotate it and replace the URL with a reference; older copies are not erased.

Attach webhooks to checks

When creating or editing an uptime check or heartbeat, you can select which webhooks should receive alerts for that check. Only webhooks subscribed to the relevant events (e.g., uptime.down/up for uptime checks) will appear as options.

Webhook payload format

OnlineOrNot POSTs JSON to your webhook URL. The format for API version 2021-05-28:

When an uptime check goes DOWN

{
  "event": "uptime.down",
  "trigger": "down",
  "name": "Some Page",
  "url": "https://example.com/health",
  "alert_priority": "HIGH"
}

When an uptime check comes UP

{
  "event": "uptime.up",
  "trigger": "up",
  "name": "Some Page",
  "url": "https://example.com/health",
  "alert_priority": "HIGH"
}

When a heartbeat stops

{
  "event": "heartbeat.down",
  "trigger": "down",
  "id": "aB3dE5gH7jK9mN2pQ4rS6tV8",
  "name": "Nightly backup job",
  "url": "https://onlineornot.com/app/heartbeats/aB3dE5gH7jK9mN2pQ4rS6tV8"
}

When a heartbeat resumes

{
  "event": "heartbeat.up",
  "trigger": "up",
  "id": "aB3dE5gH7jK9mN2pQ4rS6tV8",
  "name": "Nightly backup job",
  "url": "https://onlineornot.com/app/heartbeats/aB3dE5gH7jK9mN2pQ4rS6tV8"
}

See the webhook payload reference for the full list of events and fields.

Note: Field names and formats are stable within a version. New versions are announced before release.