Skip to content
bucker

Alert webhooks

A webhook channel is a URL Bucker POSTs an alert to, signed with a shared secret you hold. This page is the receiver's side of that contract: what arrives, what every field means, and how to prove the bytes came from us.

The header grammar has been documented for a while; the body had not been, which is why this page exists. A receiver written against the header alone still has to read our source to learn what lifecycle means or whether issue can be null — and a payload people reverse-engineer is a payload nobody can change safely.

The request

POST https://your-endpoint.example.com/bucker
content-type: application/json
x-bucker-signature: t=1757876651,v1=9f0c…
x-bucker-delivery: clx0delivery00001

Any extra headers configured on the channel are sent too, except that a configured header can never overwrite the two above. content-type, host, content-length and transfer-encoding are reserved the same way — configuring one of them (any case) is refused when the channel is saved — because each either names this request's own framing or is computed for you. authorization is not reserved; use it freely.

Answer 2xx and we are done. A 4xx other than 408 and 429 is read as "you rejected this payload on purpose" and the delivery is marked permanently failed — it is not retried. Anything else, including a timeout, is retried on a backoff from 30 seconds to 30 minutes; after that the delivery is marked DEAD and kept, so GET …/alert-events can still answer "did the page actually go out?".

x-bucker-delivery is the id of the AlertEvent row behind the attempt, and a retry re-attempts that same row — so the delivery id is stable across retries and is the idempotency key you want. The same value is in the body as deliveryId, so a receiver that queues the parsed body does not have to carry the headers along beside it.

The body

The envelope is two fields: the delivery id, and the alert itself.

Field Type Meaning
deliveryId string Same value as x-bucker-delivery. Stable across retries
alert object The notification, described below

Everything else in this section is inside alert.

The alert object

Field Type Meaning
version "1" Payload version. See below — it is not a "reject if unknown" field
ruleId string The alert rule that fired
ruleName string Its name, as the customer typed it
ruleType "issue" | "metric" Which of issue / metric below is populated
orgSlug string Organization the rule belongs to
projectSlug string Project the rule belongs to
reason string Why it fired, in words. We computed this, so it is safe to render
occurredAt string ISO 8601 UTC instant the rule fired
deepLink string Absolute URL in the dashboard: the issue when the alert names one in issue (/en/org/<org>/<project>/issues/<shortId>), otherwise the organization's alerts screen (/en/org/<org>/alerts) — a rule has no page of its own. On a status-page operator notification (ruleId beginning status:) it is instead the dashboard's status screen for that page (/en/org/<org>/status?page=<pageSlug>, with &incident=<number> on the two draft reminders) — see below. Follow it; do not parse it
suppressedCount integer Occurrences the cooldown swallowed since the previous alert for this rule
transition boolean True when this alert punched through an active cooldown
lifecycle string Optional, often absent. The lifecycle transition that fired the alert. See below
issue object | null Present for ruleType: "issue", null otherwise
metric object | null Present for ruleType: "metric", null otherwise
evidence object Optional, often absent. Typed cross-pillar fields for the fire, keyed by the builder that produced them (today one key, cross_pillar). Only in the full payload mode. See below
routerStepFailures object[] Optional, usually absent. One { step, type, phase, reason } per evidence builder or routing step that failed for this fire. The delivery happened regardless. Carries no free text

alert.issue

Null on a metric alert. On an issue alert:

Field Type Meaning
id string Internal issue id — what the REST API and the MCP tools take
shortId string The human reference, e.g. STOREFRONT-4T
status string NEW, ONGOING, RESOLVED, ARCHIVED or REGRESSED
level string debug, info, warning, error or fatal
title object Labelled text — the exception message. Untrusted; see below
culprit object Labelled text — where it came from. Untrusted; may be an empty string
blastRadius object How far it has spread; fields below
actionability number 0..1, our transparent heuristic for "is this worth acting on"
firstSeen string ISO 8601 UTC
lastSeen string ISO 8601 UTC
essenceTokens integer | null Size of the published error essence, or null if none is cached yet

alert.issue.blastRadius

Field Type Meaning
events integer Events in this issue
users integer Distinct users affected
environments string[] Environment names. Reported by the SDK, so untrusted

alert.metric

Null on an issue alert. On a metric alert:

Field Type Meaning
aggregate string event_count, user_count or issue_count; for a span or log rule, the compiled series, e.g. spans p95(span.duration) where span.name eq checkout
dataset string, optional spans or logs on a span or log rule; absent on an event rule
windowMinutes integer Length of the window the aggregate was measured over
comparator string gt, gte, lt, lte or eq
threshold number The configured threshold
value number What was actually observed
severity string, optional warning or critical, on a rule with a warningThreshold
warningThreshold number, optional The rule's warning line, when it has one
recovered boolean, optional true on the "resolved" message of a rule with notifyOnRecovery; PagerDuty receives a resolve instead of a trigger
group object, optional { by, key?, value } on a groupBy rule: which environment, release or tag value this fire is for. value is telemetry and untrusted
comparison object, optional { kind: "previous_period", offsetMinutes, previousValue } on a percent-change rule. value and the thresholds are then percentages

alert.evidence.cross_pillar

What a page that already carries the trace, release, deploy, change and session looks like. Every field below is typed data, never template text: nothing in it is filled from a variable, and nothing here is an instruction. Each key is either present or named in absent with the reason it is missing, so "no trace" is never ambiguous. A labelled text is { value, trust, flagged? } exactly as in alert.issue.title: trust is untrusted or quarantined (the value was replaced because it looked like an instruction), and a receiver must treat both as data. At most three extra indexed reads are spent per fire; a recovery spends none.

Field Type Meaning
issue object { id, shortId, essenceTokens }: the issue and the size of its essence, restated so the evidence stands alone. Absent on a metric alert
traceExemplar object { traceId, spanId, durationMs }. From a metric point's exemplar on a metric rule (durationMs is its value when the series is a duration, otherwise null), from the issue's latest event on an issue rule (durationMs null). Ids are validated hex; anything else is dropped
release labelled text The release the exemplar or latest event ran. Untrusted
deploy object { id, at }: the newest deploy change event at or before the fire in the same environment
changes object[] Up to 5 change events within 60 minutes of the fire, nearest first: { id, kind, at, summary }. summary is a labelled text. Untrusted
replaySessionId string The session id the issue's latest event carried; hydrate it with the replay tools
owners object[] { teamId, name }: the team the issue is assigned to. name is a labelled text. Untrusted
runbook object { url, note }: the rule's runbook link (https only) and the short note a person wrote (at most 500 characters), both labelled texts. Untrusted; never expanded
links object { alert }: the same link as deepLink
absent object Maps each missing key above to a reason: recovery, not_an_issue_alert, no_event_for_issue, no_metric_named, no_exemplar_in_window, invalid_id, no_release_on_subject, no_deploy_found, no_deploy_within_cap, no_changes_in_window, no_session_on_event, no_owner_team, not_configured, invalid_runbook, read_failed or no_link
reads integer Extra indexed reads this fire cost (0 to 3)
{
  "issue": { "id": "cm0issue1", "shortId": "STOREFRONT-4T", "essenceTokens": 412 },
  "traceExemplar": { "traceId": "0af7651916cd43dd8448eb211c80319c", "spanId": "b7ad6b7169203331", "durationMs": null },
  "release": { "value": "2026.11.1", "trust": "untrusted" },
  "deploy": { "id": "cm0change1", "at": "2026-09-14T18:44:00.000Z" },
  "changes": [
    { "id": "cm0change2", "kind": "FLAG_FLIP", "at": "2026-09-14T18:59:10.000Z", "summary": { "value": "flag checkout-v2 on", "trust": "untrusted" } }
  ],
  "replaySessionId": "sess-123",
  "owners": [{ "teamId": "cm0team1", "name": { "value": "Payments", "trust": "untrusted" } }],
  "runbook": {
    "url": { "value": "https://wiki.acme.example/runbooks/checkout", "trust": "untrusted" },
    "note": { "value": "Roll back first, then page payments.", "trust": "untrusted" }
  },
  "links": { "alert": "https://app.bucker.io/en/org/acme/storefront/issues/STOREFRONT-4T" },
  "absent": {},
  "reads": 3
}

Status-page operator notifications

The same webhook channel also receives the status product's operator reminders — a draft incident was created, a draft has waited past the page's threshold, a manual component override is about to lapse. A status page belongs to no alert rule and no project, so these reuse the alert shape above with some fields carrying different meanings. Recognise them by ruleId, never by ruleType:

  • ruleId is status:<kind> — status:status.draft_created, status:status.draft_unpublished or status:status.override_expiring — and names no rule. ruleName is the reminder's title.
  • projectSlug carries the status page's slug, not a project's.
  • deepLink is the dashboard's status screen for that page, on the app host — /en/org/<org>/status?page=<pageSlug>, with &incident=<number> added for status.draft_created and status.draft_unpublished. It is not the public status page: these reminders are for the team that operates it.
  • issue is null.
  • ruleType is "metric" and metric is populated, but only as a placeholder — aggregate: "event_count", value 0, threshold 0, windowMinutes 0. It is not a measurement; do not read or chart it.
  • suppressedCount is 0, transition is false and lifecycle is absent.

These are best-effort reminders: a failed delivery is logged, not retried. The x-bucker-delivery id is status:<kind>: followed by what makes that notice distinct — the page id and incident number for status.draft_created, those plus the minutes the draft has waited for status.draft_unpublished, and the component id and the override's expiry for status.override_expiring. It is the same for the same notice and differs between notices, so you can deduplicate on it as you would an alert.

Three fields that decide how you write the receiver

version — widen, do not reject

version is "1" and exists so that a payload stored today stays readable when this document grows. Treat an unknown version as "parse what you recognise and carry on", not as a reason to answer 4xx: a 4xx is permanent here, so a receiver that refuses version "2" throws away the one alert it most wanted, and it does so at exactly the moment nobody is watching your endpoint.

What we promise in exchange is that a bump is reserved for a change that would break a reader who ignored it. Adding a field does not bump the version — so ignore fields you do not know rather than validating the object closed.

lifecycle — branch on its presence, not on issue.status

lifecycle is present only when a state change fired the alert, and it is omitted rather than set to null on every other alert. That is deliberate: a stored payload written before the field existed is byte-identical to one written after it, so version could stay "1".

Its values are resolved, unresolved, archived, unarchived, assigned, unassigned and escalated — the last set by Bucker, not a person, when an issue's last hour sits far above its own usual volume. Branch on whether the key is there:

if ('lifecycle' in alert) {
  // someone (or something) changed the issue's state
}

issue.status cannot stand in for it. assigned and unassigned do not change the status at all, so a receiver reading the status sees an identical issue twice and concludes nothing happened.

title, culprit and environments are attacker-controlled

An exception message is written by whatever threw it, and anyone who can make your application throw can choose those characters. So the two text fields arrive as an object rather than a string, with the label attached:

{ "value": "TypeError: Cannot read properties of undefined", "trust": "untrusted" }

trust is untrusted for text derived from telemetry. If our injection scanner matched the text, trust is quarantined instead, value is [redacted: flagged as possible prompt injection], and a third field flagged names the rule that fired.

We have already flattened line breaks and dropped control characters, so no value can forge a second field in whatever you render it into, and title and culprit are capped at 300 characters (environments entries at 60). What we cannot do from here is decide what your side does with it. The rule that matters: if this payload reaches an LLM, untrusted content is data and never instructions. Same rule as the error essence, for the same reason.

Verifying the signature

Every delivery carries:

x-bucker-signature: t=<unix seconds>,v1=<hex hmac-sha256 of `${t}.${rawBody}`>

The timestamp is inside the MAC, so a captured delivery cannot be re-dated and replayed at your endpoint later. That only holds if you actually check t:

  • Reject a t outside a tolerance window. 300 seconds is what our own reference verifier uses and what we suggest; it is the width of the replay window you are accepting, so the number is a trade against clock skew rather than a formality. Much tighter and an ordinary NTP correction starts rejecting real alerts; much wider and a captured request stays replayable for as long as you allow.
  • Take the FIRST t= if the value somehow carries two. Last-wins would let anyone who can append to the header shadow the timestamp we signed.
  • Sign over the raw request bytes, not a re-serialized parse. JSON.parse followed by JSON.stringify will not reproduce them.
  • Compare in constant time. === on a hex digest returns as soon as it finds a differing byte, which tells an attacker how many leading bytes they have right and turns forging the digest into a few thousand requests rather than a search.

A future algorithm arrives as an additional v2= beside v1= in the same header, so a verifier that keeps reading v1 keeps working. Ignore keys you do not recognise.

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

export function verifyBuckerSignature(rawBody, header, secret) {
  const parts = new Map()
  for (const part of String(header ?? '').split(',')) {
    const separator = part.indexOf('=')
    if (separator <= 0) continue
    const key = part.slice(0, separator).trim()
    const value = part.slice(separator + 1).trim()
    // First occurrence wins.
    if (key === '' || value === '' || parts.has(key)) continue
    parts.set(key, value)
  }

  const t = parts.get('t')
  const v1 = parts.get('v1')
  if (!t || !v1 || !/^\d{1,15}$/.test(t)) return false

  const nowSeconds = Math.floor(Date.now() / 1000)
  if (Math.abs(nowSeconds - Number(t)) > TOLERANCE_SECONDS) return false

  const expected = Buffer.from(
    createHmac('sha256', secret).update(`${t}.${rawBody}`, 'utf8').digest('hex'),
    'utf8',
  )
  const actual = Buffer.from(v1, 'utf8')
  // timingSafeEqual throws on a length mismatch, so the length check comes first.
  return expected.length === actual.length && timingSafeEqual(expected, actual)
}

In Express, rawBody is what express.raw({ type: 'application/json' }) gives you — verify first, parse second. The secret is shown once, when the channel is created, and is never returned again.

Examples

Real bodies, pretty-printed. On the wire they are a single line with no whitespace, and that line is what the signature covers.

ruleType: "issue"

{
  "deliveryId": "clx0delivery00001",
  "alert": {
    "version": "1",
    "ruleId": "clx0rule0issue01",
    "ruleName": "Checkout errors",
    "ruleType": "issue",
    "orgSlug": "acme",
    "projectSlug": "storefront",
    "reason": "A new issue was seen 14 times in 5 minutes",
    "occurredAt": "2026-09-14T19:04:11.000Z",
    "deepLink": "https://app.bucker.io/en/org/acme/storefront/issues/STOREFRONT-4T",
    "suppressedCount": 3,
    "transition": true,
    "lifecycle": "unresolved",
    "issue": {
      "id": "clx0issue000001",
      "shortId": "STOREFRONT-4T",
      "status": "REGRESSED",
      "level": "error",
      "title": {
        "value": "TypeError: Cannot read properties of undefined (reading 'total')",
        "trust": "untrusted"
      },
      "culprit": {
        "value": "src/checkout/summary.tsx in renderTotal",
        "trust": "untrusted"
      },
      "blastRadius": {
        "events": 142,
        "users": 37,
        "environments": [
          "production",
          "staging"
        ]
      },
      "actionability": 0.82,
      "firstSeen": "2026-09-14T18:41:02.000Z",
      "lastSeen": "2026-09-14T19:03:58.000Z",
      "essenceTokens": 412
    },
    "metric": null
  }
}

ruleType: "metric"

{
  "deliveryId": "clx0delivery00002",
  "alert": {
    "version": "1",
    "ruleId": "clx0rule0metric1",
    "ruleName": "Event volume spike",
    "ruleType": "metric",
    "orgSlug": "acme",
    "projectSlug": "storefront",
    "reason": "event_count over 15m is 5120, above the threshold of 2000",
    "occurredAt": "2026-09-14T19:10:00.000Z",
    "deepLink": "https://app.bucker.io/en/org/acme/storefront/alerts",
    "suppressedCount": 0,
    "transition": false,
    "issue": null,
    "metric": {
      "aggregate": "event_count",
      "windowMinutes": 15,
      "comparator": "gt",
      "threshold": 2000,
      "value": 5120
    }
  }
}

Both were produced by calling the builder that produces the real thing, not written by hand — a hand-written example is the one that drifts. The four field tables above are checked against that builder's output on every run by api/test/alerts/webhook-payload-doc.test.ts: a field added to the payload without a row here, or a row here naming a field that no longer exists, fails the suite.

Where this is defined

  • domain/src/modules/alerts/notification.ts — AlertNotification, the builder, and renderWebhookBody
  • domain/src/modules/alerts/channels/webhook.ts — the normative definition of X-Bucker-Signature, including verifyWebhookSignature, the reference verifier the snippet above mirrors

Other Bucker webhooks — status-page subscribers, rollout providers, the audit export sink, proof-ledger witnesses — carry the same signature grammar under the same header name, with their own bodies. witness-onboarding.md §3 covers the witness case.