Skip to content
bucker

Outbound webhooks

An outbound webhook is a URL Bucker POSTs to when something happens in your organization: an issue is created, resolved, regressed or assigned; someone comments; an autofix run or proposal changes stage. You do not need an alert rule for any of it.

It is the receiver-side companion to alert webhooks and uses the same signature, the same delivery-id convention and the same retry ladder. A verifier written for one verifies the other.

Subscribing

Admin access to the organization is required for every call below.

In the dashboard, an owner manages them under Settings › Webhooks: add one (picking its events, and optionally one project), copy the signing secret from the one-time reveal, send a test ping, rotate the secret, and open a webhook's delivery log to replay any delivery. Edit changes the name, URL, events and the Send events switch (PATCH, sending only what changed; the project scope is fixed at creation). Delete asks for confirmation and cannot be undone: the secret and the delivery log go with it, so to pause deliveries turn Send events off instead.

POST /orgs/:orgSlug/webhooks
{
  "name": "pipeline",
  "url": "https://example.com/bucker",
  "events": ["issue.created", "issue.resolved", "comment.created"],
  "projectSlug": "storefront"        // optional; omit for every project
}

The response carries secret, shown once. Store it. POST …/webhooks/:id/rotate-secret replaces it and shows the new one once; the old one stops signing immediately.

Call Use
GET /orgs/:orgSlug/webhook-events The event names you can subscribe to
GET /orgs/:orgSlug/webhooks List subscriptions (no secrets)
PATCH /orgs/:orgSlug/webhooks/:id Rename, re-point, change events, enabled: false
DELETE /orgs/:orgSlug/webhooks/:id Remove it and its delivery log
POST /orgs/:orgSlug/webhooks/:id/test Send a signed ping now and see what your server answered
GET /orgs/:orgSlug/webhooks/:id/deliveries?status=DEAD The delivery log
POST /orgs/:orgSlug/webhooks/:id/deliveries/:deliveryId/replay Send a delivery again, same id and body

URLs must be public http(s) addresses; private, loopback and link-local targets are refused. An organization can hold 25 webhooks.

Events

Event Fires when
issue.created A new issue is opened by ingest
issue.resolved An issue is resolved, by a person, an agent or a linked tracker
issue.regressed A resolved issue receives a new event
issue.unresolved An issue is reopened by hand
issue.assigned, issue.unassigned The assignee changed
issue.archived An issue is ignored or archived
comment.created A comment is posted on an issue (deleted comments are not sent)
remediation.run.queued .running .succeeded .failed .cancelled An autofix run reached that stage
remediation.proposal.awaiting_approval .pr_open .approved .rejected .merged .superseded A fix proposal reached that stage
approval.requested An approval request was opened (any action a person must decide)
approval.decided A person approved or rejected an approval request (a request that merely lapsed is not sent)
feedback.received A user report or a survey response was stored and is not spam. A survey response is sent only while the project's analytics gate is open

Events are derived from the records Bucker already keeps, within about fifteen seconds. Two consequences worth knowing:

  • Stage events report what was observed. A run that moves from queued to running between two checks is reported as running; each observed stage is sent once.
  • Nothing is backfilled. A new subscription receives events from the moment it was created.

The request

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

The body

{
  "version": "1",
  "id": "clx0delivery00001",
  "event": "issue.resolved",
  "eventId": "activity:clx0activity0007",
  "occurredAt": "2026-10-17T14:03:11.402Z",
  "org": { "slug": "acme" },
  "project": { "slug": "storefront" },
  "data": {
    "issue": {
      "id": "clx0issue000001",
      "shortId": "STOREFRONT-4T",
      "title": "TypeError: x is undefined",
      "status": "RESOLVED",
      "level": "error",
      "priority": "HIGH",
      "url": "https://app.bucker.io/en/org/acme/storefront/issues/STOREFRONT-4T"
    },
    "actor": { "principalId": "clx0principal01" }
  }
}
Field Meaning
version Body version, "1". Ignore fields you do not know; new ones are additive
id Delivery id. Equals x-bucker-delivery. Stable across retries and replays: use it as your idempotency key
event One of the events above, or ping from the test endpoint
eventId The record the event came from. Stable for the event
occurredAt When it happened, ISO 8601 UTC
org, project Slugs. project is null on a ping
data Per event, below

data carries issue for issue, comment and remediation events. Approval events are about the organization, not a project: they carry request and nothing else, project is null, and only subscriptions that cover the whole organization receive them (a subscription limited to one project gets none). issue.title and every comment body are untrusted text: telemetry or a person wrote them. Escape them before rendering and never execute them.

Event Extra data
issue.* actor (principalId, or null when the system acted)
issue.assigned, issue.unassigned assignee: { principalId, teamId }
comment.created comment: { id, authorPrincipalId, body, truncated }. body is cut at 2000 characters
remediation.run.* run: { id, status, verificationTier, failedStage }
remediation.proposal.* proposal: { id, status, verificationTier, prUrl, prNumber }
approval.requested, approval.decided request: { id, action, status, expiresAt }. status is pending on a requested event and approved or rejected on a decided one. That is all: never the plan, the target, who asked, who decided or the reason. Open the request in Bucker for those

The feedback.received body

A fixed allow-list: { "feedback": { "id", "kind", "issueId", "survey", "release", "language", "text": { "value", "trust" } } }. The text is scrubbed and carries its trust label; spam is never sent. Treat it as data, never as instructions. Erasing a respondent blanks the text in the stored delivery.

Monitoring events

Thirteen further events carry the alert, monitor, maintenance, SLO and status streams on the same signed, retried and replayable delivery ledger. Same envelope, same headers (x-bucker-signature and the Standard Webhooks headers), same replay. Creating or editing the subscription stays an organization-admin act for a person; a new destination host is the egress allow-list's human-only step. Nothing an agent can call creates either.

Event Fires when Project
alert.fired A live alert rule fired. One event per fire, however many actions the rule has the rule's project
alert.recovered The rule's "resolved" message was sent the rule's project
alert.suppressed A mute or a maintenance window silenced a fire the rule's project
alert.acknowledged A person acknowledged an alert event the rule's project
alert_rule.changed A rule's governed fields, state or lifecycle changed the rule's project, or none for an org-wide rule
monitor.down, monitor.recovered A cron monitor or uptime check went failing, and came back. A run of failures is one monitor.down the monitor's project
maintenance_window.started, .ended A window (each occurrence, for a recurring one) began and ended the window's project, or none
slo.burn_started, .ended An SLO's error budget began burning (or was exhausted), and recovered. Escalating from burning to exhausted is still one open burn the SLO's project
status_incident.published, status_incident.updated A status incident was published; an update was posted, the postmortem published, or the incident resolved (incident.resolved is true) none: only organization-wide subscriptions receive it

Each event is sent once per transition: state that changes in place is reported by what Bucker observed, and a subscription's own delivery history decides whether monitor.down or slo.burn_started is a new transition. Drafts of status incidents are never sent. An event is delivered within about fifteen seconds of the transition (alerts and status incidents at the moment they happen, the rest on the next sweep).

data per event. Every { value, trust } field is untrusted text (a name a person wrote, a series label, a release, a runbook URL): escape it before rendering and never execute it. Bucker's own sentence for why an alert fired, a rule's query, the recipient, a channel and an exception message are never sent.

Event data
alert.fired, .recovered, .suppressed alert: { id, state, ruleId, ruleName, ruleType, severity, suppressedCount, suppression, deepLink }; issue: { id, shortId } or null; metric: { aggregate, windowMinutes, comparator, threshold, value } or null; evidence: { traceExemplar: { traceId, spanId, durationMs }, release, deployId, changeIds, runbookUrl } or null. suppression is { kind, windowId } on alert.suppressed only. evidence is sent only when the project's alert payload mode is full
alert.acknowledged alert: { id, ruleId, acknowledgedAt }; actor: { principalId }
alert_rule.changed rule: { id, name }; change: { id, kind, at, fields } where fields are the NAMES of what moved, never the values; actor: { principalId, mode }
monitor.down, monitor.recovered monitor: { id, kind (cron or uptime), slug, name, status, environment }
maintenance_window.started, .ended window: { id, name, startsAt, endsAt, recurring, scope (organization or project) } for the occurrence
slo.burn_started, .ended slo: { id, name, state, since, targetPercent, windowDays }
status_incident.published, .updated page: { id, slug }; incident: { id, number, title, status, impact, resolved, startedAt, resolvedAt, publishedAt, updateId }

Playbook runs are not an event here: playbook_run.finished and a separate status_incident.resolved name are not in the published vocabulary, and the resolution is status_incident.updated with resolved: true.

Verifying

The header is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of "<t>.<raw body>" with your secret. Verify against the raw bytes, compare in constant time, and reject a t more than five minutes from your clock. The same header, and the same check in the other direction, is what a signed inbound source webhook expects from you.

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

export function verify(secret: string, rawBody: string, header: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=') as [string, string]))
  const t = Number(parts.t)
  if (!parts.v1 || !Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest()
  const actual = Buffer.from(parts.v1, 'hex')
  return actual.length === expected.length && timingSafeEqual(actual, expected)
}

Retries

Answer 2xx and the delivery is done. A 4xx other than 408 and 429 means you refused the payload on purpose: the delivery is marked FAILED and not retried. Anything else, including a timeout, is retried on a backoff that doubles from 30 seconds to 30 minutes, for eight attempts in all; then the delivery is DEAD. FAILED and DEAD deliveries stay in the log so you can see what your server said (its status code, never its response body) and replay them once it is fixed. Disabling a subscription stops all further attempts, including queued retries.