Webhook payloads
A webhook channel sends each alert as a JSON POST to your URL. Check each request’s signature first: see Verify webhook signatures.
The request
Section titled “The request”POST /hooks/ottertrail HTTP/1.1Host: example.comContent-Type: application/jsonUser-Agent: Ottertrail/0.2.0 (webhooks)Ottertrail-Event: check.downOttertrail-Delivery: 2f0c3a9e-8d41-4b7a-9c55-6a1e2b3c4d5eOttertrail-Timestamp: 1794983405Ottertrail-Signature: v1=5d4c…User-Agent names the instance’s version.
The body
Section titled “The body”{ "version": 1, "id": "6b1f3c1e-6f0c-4b65-8f15-0a5a7b0a4b10", "type": "check.down", "time": "2026-11-18T06:30:00.000Z", "project": { "id": "0d6e5f80-0c4f-4b8e-9d3a-3f8f6a1c2b7e", "name": "Shop" }, "subject": { "type": "check", "id": "c0ffee00-0000-4000-8000-000000000001", "name": "API health", "url": "https://api.example.com/health", "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "API down" }, "message": "Shop: the check \"API health\" (https://api.example.com/health) is down. It answered 503, which does not count as up.", "url": "https://analytics.example.com/projects/0d6e5f80-0c4f-4b8e-9d3a-3f8f6a1c2b7e/uptime/c0ffee00-0000-4000-8000-000000000001"}| Field | Meaning |
|---|---|
version |
1. A change that can break a receiver comes as a new version. New fields can be added to version 1. |
id |
The notification’s ID. It is the same for each channel that gets it, and on each retry. Use it to drop a repeat. |
type |
The event type. See below. |
time |
When it happened, in ISO 8601, in UTC. |
project |
The project’s ID and name. null for a notification about no project, such as a test. |
subject |
What the notification is about. Its values are text, numbers, true, false, or null. Alerts include ruleId and ruleName, the rule that sent it. |
message |
One or two sentences about what happened, as the alert email says it. |
url |
The dashboard page about it. |
Ignore a type or a field that you do not know.
Event types
Section titled “Event types”| Type | Sent when |
|---|---|
check.down |
An uptime check goes down. |
check.up |
It is no longer down: up again, paused, or its URL changed. |
certificate.expiring |
A check’s TLS certificate expires within the rule’s number of days. |
certificate.renewed |
Its expiry moved past the rule’s days, or the check no longer reports a certificate. |
error.new |
An error group is seen for the first time. |
error.regressed |
A resolved error group happens again. |
error.spike |
Errors in the rule’s window reach its threshold. |
error.spike_resolved |
They stay below it for the same window. |
route.latency |
A route’s or service’s p95 or p99 duration over the window is above the threshold. |
route.latency_resolved |
It stays at or below it for the same window. |
route.failures |
A route’s or service’s failed share over the window is above the rule’s percentage. |
route.failures_resolved |
It stays at or below it for the same window. |
metric.threshold |
A metric is above, or below, the rule’s value over the window. |
metric.threshold_resolved |
It is back on the right side for the same window. |
alert.held_back |
A rule held notifications back after it sent 20 in an hour. Sent once the hour ends, with the number held back. |
test |
Someone sends a test from the channel’s settings. |
The subject of each type
Section titled “The subject of each type”check.down and check.up
Section titled “check.down and check.up”| Field | Meaning |
|---|---|
type |
check |
id, name, url |
The check |
certificate.expiring and certificate.renewed
Section titled “certificate.expiring and certificate.renewed”{ "type": "certificate", "checkId": "c0ffee00-0000-4000-8000-000000000001", "checkName": "API health", "url": "https://api.example.com/health", "host": "api.example.com", "expiresAt": "2026-11-28T12:00:00.000Z", "days": 14, "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "Certificates"}certificate.renewed has no days. Its expiresAt is the new expiry, or null when the check no longer reports a certificate.
error.new and error.regressed
Section titled “error.new and error.regressed”{ "type": "error", "fingerprint": "1-3f2a9c1d0b7e6a5f4c3d", "errorType": "TypeError", "message": "Cannot read properties of undefined (reading 'total')", "environment": "production", "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "New errors"}error.regressed also has resolvedAt, when the group was resolved.
error.spike and error.spike_resolved
Section titled “error.spike and error.spike_resolved”{ "type": "errors", "fingerprint": null, "environment": "production", "count": 27, "threshold": 20, "windowMinutes": 10, "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "Error spike"}fingerprint is the group’s ID for a rule on one group, and null for a rule on all errors.
route.latency and route.latency_resolved
Section titled “route.latency and route.latency_resolved”{ "type": "route", "service": "checkout", "route": "GET /cart", "environment": "production", "windowMinutes": 10, "requests": 1204, "percentile": "p95", "valueMs": 812.4, "thresholdMs": 500, "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "Cart latency"}percentile is p95 or p99. valueMs is rounded to 3 decimals. For a rule on a whole service, route is null.
route.failures and route.failures_resolved
Section titled “route.failures and route.failures_resolved”{ "type": "route", "service": "checkout", "route": null, "environment": "production", "windowMinutes": 5, "requests": 480, "failed": 31, "failedPercent": 6.458, "thresholdPercent": 5, "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "Checkout failing"}A request failed when its span’s status is Error.
metric.threshold and metric.threshold_resolved
Section titled “metric.threshold and metric.threshold_resolved”{ "type": "metric", "metric": "http.server.request.duration", "metricKind": "histogram", "aggregate": "p95", "direction": "above", "value": 812.4, "threshold": 500, "unit": "ms", "environment": "production", "host": "web-1", "attributeKey": null, "attributeValue": null, "windowMinutes": 10, "ruleId": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "ruleName": "Slow pages"}| Field | Values |
|---|---|
metricKind |
gauge, counter, updown, or histogram |
aggregate |
avg, min, or max for a gauge. rate (per second) for a counter. sum for an up-down counter. p50, p95, or p99 for a histogram. |
direction |
above or below |
attributeKey, attributeValue |
The attribute that the rule is narrowed to, or null |
alert.held_back
Section titled “alert.held_back”{ "type": "rule", "id": "5a2c7e10-3b4d-4e6f-8a9b-0c1d2e3f4a5b", "name": "New errors", "held": 35, "cap": 20}Delivery
Section titled “Delivery”- A
2xxanswer within 10 seconds counts as delivered. Ottertrail does not read the answer’s body. - A redirect, a
4xxor5xx, no answer in time, or a failed connection is a failure. Ottertrail does not follow redirects. - A failure is tried again, eight attempts in about an hour. See Retries and repeats.
- A channel takes at most 60 deliveries in an hour. Past that, deliveries are recorded as failed without being sent.