Create a webhook

Webhooks let you notify another system about selected BIMP changes. Use the event as a signal, then retrieve current BIMP state when the receiving workflow needs more detail.

Choose a destination

Open Settings → Integrations → Webhooks. If you are an Owner or Security Administrator, you can configure:

• Webhook, which sends a structured CloudEvents JSON document to HTTPS;
• Slack, which sends a concise message to a Slack incoming webhook; or
• Discord, which sends a concise message to a Discord webhook.

Email is not currently a destination type. A generic webhook can connect to an email service operated by your organization.

Add a webhook

Choose Add webhook, then select the type, scope, and events. Enter the endpoint and save the webhook. A scope can cover:

• the organization;
• events routed to one team; or
• one Policy Group.

Policy Groups can inherit the organization’s default notification team, choose another team, or disable inherited routing. Teams are notification audiences; they do not authorize or own policy.

Endpoint URLs are encrypted and are not returned after creation. BIMP shows only a masked preview. For a generic webhook, retain the signing secret shown after creation. BIMP shows it only once.

Select public events

Use the discoverable catalog at:

GET /api/v1/event-types

The current public catalog covers Policy Group, policy mapping, Snooze Request, and remediation pull-request state changes. Internal commands, raw failures, provider receipts, and administrative identity events are not available for delivery.

Verify a generic webhook

Generic webhooks include Standard Webhooks headers:

webhook-id: <CloudEvent id>
webhook-timestamp: <Unix seconds>
webhook-signature: v1,<base64 signature>

Verify the exact request body before parsing it, reject stale timestamps, and deduplicate with webhook-id.

BIMP sends a minimized public CloudEvent. It excludes provider credentials, email addresses, actor identifiers, branch and file paths, raw errors, and arbitrary internal metadata.

Send a test

After creating or replacing the endpoint, choose Test delivery. Confirm that the receiver:

1. accepted HTTPS delivery;
2. validated the signature for a generic webhook;
3. recorded the CloudEvent ID; and
4. handled the event without relying on excluded internal fields.

Do not rely on the destination until the test succeeds.

Understand retries and recovery

Any 2xx response succeeds. BIMP retries 429, retryable 5xx, and network failures with bounded backoff. A valid Retry-After value is honored within the maximum delay. 410 Gone disables the destination.

Failed attempts become visible on the Webhooks page and can become dead letters. Correct the receiver, then replay the public event by its CloudEvent ID. Replays use the same event ID so normal deduplication still works.

BIMP validates HTTPS endpoints, pins DNS for delivery, and rejects loopback, link-local, private, reserved, or mixed public/private destinations.

Replace endpoints and rotate secrets

Open the webhook row actions to test delivery, replace an endpoint, rotate a generic webhook signing secret, replay a dead letter, or delete the webhook.

Rotation invalidates the previous secret immediately and shows the replacement only once. Coordinate the receiver update before rotating so valid events are not sent to a verifier that still has the old secret.