Webhooks

A webhook is an HTTP endpoint you control that bichito calls every time a configured event happens. Use them to forward reports to Slack, Discord, your on-call system, an internal log, or anywhere your team already lives.

Webhooks are configured per honeycomb — manage them in /{hive}/honeycombs/{id}/integrations.

Events

Three event types today:

Event	Fires when
bug.created	A new bichito arrives.
bug.updated	Status, severity, assignee, labels, or duplicate-of change.
bug.commented	A comment is posted on a bichito.

When you register a webhook you pick which events it subscribes to — at least one is required.

Payload shape

Default ("raw") payload, identical across events:

{
  "event": "bug.created",
  "delivery_id": "wd_01HV…",
  "honeycomb_id": 42,
  "honeycomb_name": "Acme web",
  "bug": {
    "id": 1234,
    "title": "Login button broken on Safari",
    "description": "...",
    "status": "open",
    "severity": "high",
    "url": "https://acme.com/login",
    "user_agent": "Mozilla/5.0 ...",
    "reporter_email": "user@example.com",
    "reporter_identifier": null,
    "assignee_id": null,
    "labels": [{ "id": 5, "name": "regression", "color": "#ef4444" }],
    "created_at": "2026-05-07T11:42:00Z"
  }
}

For bug.updated, the payload also carries changes (the same shape /inbox uses for SSE — see Streams for the field list).

For bug.commented, it carries comment_id, comment_body, author_id.

Headers

Every delivery includes:

Header	Value
Content-Type	application/json; charset=utf-8
User-Agent	bichito-webhook/1.0
X-Bichito-Event	The event type (e.g. bug.created)
X-Bichito-Delivery	The unique delivery id (matches delivery_id in the body, useful for de-dup)

Transforms

bichito ships out-of-the-box transforms that re-shape the raw payload into formats Slack and Discord accept directly — no glue code on your side.

• transform: "raw" — the JSON shown above. For your own services.
• transform: "slack" — Slack incoming-webhook block kit. Paste a Slack webhook URL and you're done.
• transform: "discord" — Discord embed. Same idea.

See dedicated walkthroughs in Slack and Discord.

Retries

If your endpoint returns a non-2xx (or doesn't respond within 10 seconds), we retry with exponential backoff:

• Attempt 1: immediate.
• Attempt 2: ~30 seconds later.
• Attempt 3: ~2 minutes.
• Attempt 4: ~10 minutes.
• Attempt 5: ~1 hour.

After 5 failed attempts the delivery is marked failed; we don't retry further. You can manually retry a failed delivery from the dashboard if you fixed the receiving end.

Delivery log

The webhook detail page in the dashboard lists every delivery for that webhook with:

• Event type
• Status code returned
• Response body (truncated to 1KB)
• Attempt number
• Timestamp

Useful to confirm a webhook fired, debug a 404, or verify the payload your service received.

Limits

• Pro plan only. Free hives can register webhooks but they don't deliver — paywall at /{hive}/billing.
• No hard rate limit on the receiving side — if your endpoint is slow, the queue piles up and we'll start dropping new events after the delivery backlog reaches 100 per webhook. Keep your handler fast (<2s) or use a queue on your side.

Security

We don't sign payloads with HMAC today. Validate authenticity by:

• Pointing the webhook at a URL with an unguessable path (/hooks/bichito-{long-random}).
• Only accepting POSTs (no GET, no PUT).
• Optional: stash the delivery_id and reject duplicates within a 1-hour window so a leaked URL replayed at scale can't flood you.

Signed payloads are on the post-MVP list.