Webhooks

Receive real-time notifications when incidents are created, updated, resolved, or reopened. HMAC-SHA256 signed, with automatic retry and delivery tracking.

Overview

DebugBundle webhooks deliver real-time HTTP POST notifications to your endpoints when incidents and bundles change. Use webhooks to:

Alert your team in Slack, Discord, or PagerDuty
Trigger CI/CD pipelines on incident creation
Sync incident state to external issue trackers
Build custom dashboards and monitoring

Event Types

Event	Trigger
`bundle.created`	A new debug bundle is generated for an incident
`bundle.updated`	An existing bundle receives additional events
`bundle.resolved`	An incident is marked resolved
`bundle.reopened`	A previously resolved incident receives new events
`improvement_bundle.created`	An improvement analysis bundle is generated
`incident.spike_detected`	An incident's occurrence rate spikes
`verification.passed`	Webhook verification test succeeded
`verification.failed`	Webhook verification test failed

Creating a Webhook

Via CLI

debugbundle webhook create \
  --project-id proj_xxx \
  --url https://example.com/webhooks/debugbundle \
  --event bundle.created,bundle.resolved,bundle.reopened

Via API

curl -X POST https://api.debugbundle.com/v1/webhooks \
  -H "Authorization: Bearer dbundle_mem_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xxx",
    "url": "https://example.com/webhooks/debugbundle",
    "events": ["bundle.created", "bundle.resolved", "bundle.reopened"]
  }'

Response includes a signing_secret — save it immediately. It is shown once and never again.

Filters

Webhooks support optional filters to narrow which events trigger delivery:

Filter	Type	Description
`environment`	`string[]`	Only deliver for these environments
`service`	`string[]`	Only deliver for these services
`severity_min`	`string`	Minimum severity: `low`, `medium`, `high`, `critical`
`bundle_type`	`string[]`	Filter by bundle type: `failure`, `improvement`
`verification`	`boolean`	Include or exclude verification events

debugbundle webhook create \
  --project-id proj_xxx \
  --url https://example.com/webhooks/critical \
  --event bundle.created \
  --environment production \
  --severity-min high

Payload Structure

Bundle Lifecycle Events

bundle.created, bundle.updated, bundle.resolved, improvement_bundle.created:

{
  "event": "bundle.created",
  "occurred_at": "2025-01-15T10:30:00.000Z",
  "project_id": "proj_xxx",
  "bundle_id": "bun_xxx",
  "bundle_type": "failure",
  "severity": "high",
  "service": "api",
  "environment": "production",
  "verification": false,
  "summary": "TypeError: Cannot read property 'id' of undefined",
  "links": {
    "bundle": "https://app.debugbundle.com/bundles/bun_xxx",
    "reproduction": "https://app.debugbundle.com/bundles/bun_xxx/reproduction"
  }
}

Incident Lifecycle Events

bundle.reopened, incident.spike_detected:

{
  "event_type": "bundle.reopened",
  "incident_id": "inc_xxx",
  "project_id": "proj_xxx",
  "occurred_at": "2025-01-15T10:30:00.000Z",
  "service_name": "api",
  "environment": "production",
  "severity": "high",
  "regression_after_deploy": true,
  "deploy_version": "1.2.3",
  "deploy_commit_sha": "abc123",
  "deploy_branch": "main",
  "deploy_deployed_at": "2025-01-15T09:00:00.000Z",
  "minutes_since_deploy": 90
}

Verification Events

verification.passed, verification.failed:

{
  "delivery_id": "del_xxx",
  "event": "verification.passed",
  "event_type": "verification.passed",
  "occurred_at": "2025-01-15T10:30:00.000Z",
  "project_id": "proj_xxx",
  "webhook_id": "whk_xxx",
  "incident_id": "inc_xxx",
  "test": true,
  "data": {
    "message": "Webhook verification passed."
  }
}

Signature Verification

Every webhook delivery includes an HMAC-SHA256 signature in the X-DebugBundle-Signature header. Always verify this signature before processing the payload.

Node.js

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

function verifyWebhook(
  body: string,
  signature: string,
  signingSecret: string
): boolean {
  const expected = createHmac('sha256', signingSecret)
    .update(body)
    .digest('hex');

  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhooks/debugbundle', (req, res) => {
  const signature = req.headers['x-debugbundle-signature'];
  const rawBody = req.body; // Ensure raw string, not parsed JSON

  if (!verifyWebhook(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  // Process the event...
  res.status(200).send('OK');
});

Python

import hashlib
import hmac

def verify_webhook(body: bytes, signature: str, signing_secret: str) -> bool:
    expected = hmac.new(
        signing_secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Delivery Lifecycle

Status	Description
`pending`	Queued for delivery
`delivered`	2xx response received
`retrying`	Failed, scheduled for retry
`failed`	All retry attempts exhausted
`disabled`	Webhook auto-disabled after repeated failures

Retry Behavior

Failed deliveries retry with exponential backoff. After sustained failures, the webhook is automatically disabled. You can re-enable and retry manually.

Lifecycle webhook deliveries also count against the plan's shared monthly monthly_webhook_deliveries allowance. When that allowance is exhausted, DebugBundle stops creating new lifecycle webhook delivery intents until the monthly reset or until more capacity is added. Existing delivery history remains visible.

Viewing Deliveries

debugbundle webhook deliveries whk_xxx --project-id proj_xxx --limit 20

Retrying a Delivery

debugbundle webhook retry whk_xxx del_xxx --project-id proj_xxx

Testing

Send a test delivery to verify your endpoint:

debugbundle webhook test whk_xxx --project-id proj_xxx

By default this sends a verification.passed event. To test failure:

debugbundle webhook test whk_xxx --project-id proj_xxx --event verification.failed

Synthetic test deliveries consume the same lifecycle webhook allowance. When that meter is exhausted, the API rejects the test with 429 monthly_quota_exceeded and a Retry-After header.

Managing Webhooks

# List webhooks
debugbundle webhook list --project-id proj_xxx

# Update a webhook
debugbundle webhook update whk_xxx --project-id proj_xxx --url https://new-endpoint.example.com

# Disable a webhook
debugbundle webhook update whk_xxx --project-id proj_xxx --is-enabled false

# Delete a webhook
debugbundle webhook delete whk_xxx --project-id proj_xxx

Next Steps

API Webhooks Endpoints — Full API reference for webhook CRUD
Security — DebugBundle's security model

Webhooks

On this page