DebugBundle
CLI

Webhook Management

Create, test, and manage webhooks with the DebugBundle CLI.

The CLI provides full CRUD operations for webhooks, plus delivery management and testing.

List Webhooks

debugbundle webhook list --project-id proj_01HXYZ...

Output:

{
  "webhooks": [
    {
      "webhook_id": "wh_01HABC...",
      "url": "https://myapp.com/webhooks/debugbundle",
      "events": ["bundle.created", "bundle.resolved"],
      "is_enabled": true,
      "filters": {
        "environments": ["production"],
        "services": [],
        "severity_min": null,
        "bundle_types": []
      }
    }
  ]
}
FlagTypeDefaultDescription
--project-idstring—Required. Project to list webhooks for.
--limitnumber50Maximum number of webhooks to return.
--auth-filestring~/.debugbundle/auth.jsonPath to auth state file.
--jsonbooleanfalseOutput as JSON.

Create Webhook

debugbundle webhook create \
  --project-id proj_01HXYZ... \
  --url https://myapp.com/webhooks/debugbundle \
  --event bundle.created,bundle.resolved \
  --environment production \
  --severity-min high

Output:

{
  "webhook": {
    "webhook_id": "wh_01HDEF...",
    "url": "https://myapp.com/webhooks/debugbundle",
    "signing_secret": "whsec_a1b2c3d4e5f6...",
    "events": ["bundle.created", "bundle.resolved"],
    "is_enabled": true
  }
}

The signing_secret is shown only once at creation. Copy it immediately to verify webhook signatures. See Webhooks for HMAC-SHA256 verification.

FlagTypeDefaultDescription
--project-idstring—Required. Project to create the webhook for.
--urlstring—Required. HTTPS endpoint URL to receive deliveries.
--eventstring—Required. Comma-separated event types to subscribe to.
--environmentstring—Filter: only deliver for these environments (comma-separated).
--servicestring—Filter: only deliver for these services (comma-separated).
--severity-minstring—Filter: minimum severity (low, medium, high, critical).
--bundle-typestring—Filter: only deliver for these bundle types (comma-separated).
--verificationbooleantrueWhether signature verification is required.
--is-enabledbooleantrueWhether the webhook is active.
--auth-filestring~/.debugbundle/auth.jsonPath to auth state file.
--jsonbooleanfalseOutput as JSON.

Available Event Types

EventTrigger
bundle.createdNew debug bundle generated.
bundle.updatedExisting bundle updated with new data.
bundle.resolvedIncident marked as resolved.
bundle.reopenedPreviously resolved incident regressed.
improvement_bundle.createdImprovement bundle generated.
incident.spike_detectedUnusual spike in incident occurrences.
verification.passedWebhook verification test succeeded.
verification.failedWebhook verification test failed.

Update Webhook

debugbundle webhook update wh_01HDEF... \
  --event bundle.created,bundle.resolved,incident.spike_detected \
  --severity-min medium

Partial update — only the specified fields are changed. Omitted fields remain unchanged.

FlagTypeDescription
--urlstringNew endpoint URL.
--eventstringReplace subscribed event types (comma-separated).
--environmentstringReplace environment filter (comma-separated).
--servicestringReplace service filter (comma-separated).
--severity-minstringUpdate minimum severity filter.
--bundle-typestringReplace bundle type filter (comma-separated).
--verificationbooleanUpdate verification requirement.
--is-enabledbooleanEnable or disable the webhook.
--auth-filestringPath to auth state file.
--jsonbooleanOutput as JSON.

Delete Webhook

debugbundle webhook delete wh_01HDEF...

Permanently removes the webhook. Pending deliveries are cancelled.

Test Webhook

Send a synthetic signed delivery to verify your endpoint:

debugbundle webhook test wh_01HDEF...

The test command sends a verification.passed event by default. Specify a different event:

debugbundle webhook test wh_01HDEF... --event verification.failed

Use this to verify that your webhook endpoint correctly validates HMAC-SHA256 signatures and processes payloads.

FlagTypeDefaultDescription
--eventstringverification.passedEvent type to send (verification.passed or verification.failed).
--auth-filestring~/.debugbundle/auth.jsonPath to auth state file.
--jsonbooleanfalseOutput as JSON.

View Deliveries

List recent deliveries for a webhook:

debugbundle webhook deliveries wh_01HDEF...

Output:

{
  "deliveries": [
    {
      "delivery_id": "del_01HGHI...",
      "status": "delivered",
      "event_type": "bundle.created",
      "attempt_count": 1,
      "created_at": "2026-03-24T10:30:00Z",
      "delivered_at": "2026-03-24T10:30:01Z"
    },
    {
      "delivery_id": "del_01HJKL...",
      "status": "failed",
      "event_type": "bundle.resolved",
      "attempt_count": 5,
      "created_at": "2026-03-24T09:00:00Z",
      "last_attempt_at": "2026-03-24T10:00:00Z"
    }
  ]
}

Delivery Statuses

StatusDescription
pendingDelivery queued, not yet attempted.
deliveredSuccessfully delivered (2xx response).
retryingDelivery failed, retrying with exponential backoff.
failedAll retry attempts exhausted.
disabledWebhook auto-disabled after 50 consecutive failures.

Retry a Delivery

Retry a specific failed delivery:

debugbundle webhook retry wh_01HDEF... del_01HJKL...

This resets the delivery to retrying status and re-queues it for delivery. Useful for manual recovery of failed or disabled deliveries.

Next Steps

Token Management

Create, list, and revoke project and member tokens with the DebugBundle CLI.

Alert Management

Configure alert channels and conditions with the DebugBundle CLI.

On this page

List WebhooksCreate WebhookAvailable Event TypesUpdate WebhookDelete WebhookTest WebhookView DeliveriesDelivery StatusesRetry a DeliveryNext Steps