Webhook alerts: payload, headers and retries

Besides email and the notification bell in the app, Pingsured can send an alert as an HTTP request to a URL you choose — your incident tool, a chat integration, an automation platform or your own endpoint. Webhooks are available on the Team plan and above. An account owner or manager sets them up, either for one ping or as the default for every ping in the account.

The request

Every alert is a POST with a JSON body:

the URL must use https;
Content-Type: application/json;
User-Agent: Pingsured-Alarm/1;
up to 3 redirects are followed;
your endpoint has 10 seconds to answer with a 2xx status.

Addresses in private, loopback or link-local networks are refused, including when a public hostname resolves to one or a redirect points to one.

The payload

Field	Meaning
`event`	`alarm.fired`, or `alarm.fired.test` for the test button
`version`	the payload version, currently `1`
`account_id`	the account the ping belongs to
`task_id`	the ping's ID
`task_name`	the ping's name as shown in the app
`channel`	always `webhook`
`trigger`	the rule that fired, such as `first_error` or `first_ok`
`result.status`	the ping's status now: `ok`, `warning`, `error` or `unknown`
`result.prev_status`	the status before this change, if there was one
`result.started_at`	when the check that produced this result ran, in ISO 8601 UTC
`result.location`	the location whose checks fired the alert, such as `de` or `us-west`

A typical alert when a site stops answering:

event: alarm.fired
trigger: first_error
result.status: error, result.prev_status: ok

When it recovers, the alert is the same except that trigger is first_ok and the two statuses are the other way round.

Headers for routing and deduplication

X-Pingsured-Event repeats the event name, so you can route without parsing the body.
X-Pingsured-Event-Version repeats the payload version.
X-Pingsured-Delivery identifies the delivery. It stays the same when a delivery is retried, so store it and ignore a second request with an ID you have already processed.

Retries

When your endpoint does not answer in time, cannot be reached or answers 408, 425, 429 or any 5xx status, the delivery is retried — 5 attempts in all, 30 seconds, 5 minutes, 30 minutes and 2 hours apart. Any other 4xx answer is final and is not retried. Nor is a delivery that is refused outright: a plain http URL, a private address or too many redirects.

When webhooks are sent

A webhook follows the same rules as every other alert channel:

Which changes. The recommended setup alerts on the first failure and on the recovery. You can also be alerted on every failing result.
How many failures first. A threshold such as "3 of the last 5 checks" keeps a single slow response from paging anyone. Alarm and recovery thresholds are set separately.
How often. Repeat alerts for the same ping and channel are held back for 15 minutes; a change of status is always sent at once.
Where. Each location a ping is checked from is judged on its own, and the ping counts as failing when it is failing from any one of them.

Not available yet

Requests are not signed. Until they are, use a URL with a hard-to-guess path or token, and treat X-Pingsured-Delivery as an identifier, not as proof of origin.
One webhook URL per ping, plus one account-wide default.