Skip to content
downpipes docs

Send downpipes alerts to your own webhook

A webhook channel posts each event to any HTTPS endpoint you run, in a documented JSON shape you map yourself. This is the channel to point at your own automation or at a tool without a dedicated channel here.

What you need

  • An HTTPS endpoint you control that can accept a JSON POST.
  • Access to the downpipes console with permission to configure notifications (Operator, Approver or Owner) to add and test the channel.

Set it up

  1. Stand up, or choose, the HTTPS endpoint that will receive the events. It must be https and must not be a workers.dev host.
  2. In the downpipes console, open Notifications, choose Add a channel and pick Webhook (generic HTTPS POST). Adding a channel needs permission to configure notifications, so an Operator, Approver or Owner can add one.
  3. Paste the endpoint URL into the HTTPS URL field. It must be https and carry no embedded credentials. Name the channel and save it, then a rule routes events to it.
  4. Choose Test on the channel row to confirm delivery without sending real alert content, then check your endpoint received the POST.

What lands at your endpoint

Each event arrives as a downpipe-event-v1 JSON body:

{"kind":"downpipe-event-v1","at":"2026-07-05T04:14:08.123Z","event":"backup-failure","severity":"critical","downpipe":{"id":"dp_9f2","name":"prod-kv"},"detail":"prod-kv last run failed","dedupKey":"downpipe:dp_9f2:backup-failure"}

The downpipe object is omitted for an account-level event. Every body carries dedupKey, and a recovery also carries recovered: true. Map these fields to whatever your endpoint or downstream tool expects.

The downpipe-event-v1 body can get more optional fields in a later engine release. Make your endpoint ignore keys that it does not know. An endpoint that rejects unknown keys can reject every body after such a release, critical alerts included. If that endpoint also answers with a 2xx status, downpipes records the delivery as a success. Change such an endpoint before you upgrade the engine.

Good to know

  • The outbound call is screened like every channel. downpipes re-screens the destination host at send time with the same egress guard the other channels use, and refuses an internal, private or link-local target by default. The console offers no control that waives that, so a private address cannot be set as a webhook channel from the console: put a public HTTPS front in place of it, or use the per-channel internal-sink override described in webhook egress security. The body carries only operational facts (the event, severity, downpipe id and name, a one-line detail, the time, and a correlation key built from the downpipe id and the event, and a recovered marker), never a secret or the data being backed up.
  • An operator egress allowlist applies too. When your account sets one, the endpoint host must also match an entry on the list.
  • A wildcard entry covers subdomains. An entry such as *.example.com matches subdomains at any depth and never the bare example.com (screenEgressAllowlist, engine/src/notify/types.ts).
  • Your endpoint does the dedup and the auto-resolve. The body gives it two fields for this. dedupKey is downpipe:<id>:<event>, or account:<event> for an account-level event. It is the same key the PagerDuty, Jira Service Management / Opsgenie and ServiceNow channels use, and a trigger and the recovery that clears it carry the same value. recovered is present, and true, only on the recovery of a backup-failure, backup-stale, replication-degraded or run-at-risk-eviction alert. A recovery also carries the same event and severity as the alert it clears, with a new detail line and at time. An account-level event has one key for each event name. So repeated alerts of one account-level event, for example two recovery-code-used events, group onto one open alert, and no recovery closes it. The canary is different: its recovery arrives as the canary-recovered event. That event has no recovered field, and its key is account:canary-recovered, so a mapping keyed on recovered does not close a canary-dead alert.

Last updated .