Create a webhook

Create a webhook when:

• you have a Snooze Request to review;
• a remediation pull request has been created or has failed;
• a Policy Group or mapping has changed; or
• you want to create or update a ticket in another system.

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

Before you begin

You need:

• Owner or Security Administrator access in BIMP;
• permission to create an integration in the destination platform;
• a destination channel, space, project, or queue; and
• a secure place to store the endpoint URL and, for a generic webhook, the signing secret.

Choose a destination

Open Settings → Integrations → Webhooks. If you are an Owner or Security Administrator, you can create a Slack destination or a generic Webhook destination.

Platform	BIMP webhook type	How to connect it
Slack	Slack	Create a Slack incoming webhook and paste its URL into BIMP. BIMP formats the message for Slack.
Microsoft Teams	Webhook	Use a Teams webhook workflow to receive and transform the BIMP event before posting it to a channel or chat.
Google Chat	Webhook	Use a receiver or automation workflow to transform the BIMP event into a Google Chat incoming webhook message.
Jira	Webhook	Use an Atlassian Automation incoming webhook with a receiver or workflow that verifies and maps the BIMP event.
ServiceNow	Webhook	Create a ServiceNow Scripted REST API to verify the event and create or update the required record.

What is a receiver?

A receiver is a public HTTPS endpoint or automation workflow that accepts a BIMP event and converts it into the format required by another platform.

Slack is a native destination. Generic webhooks send a signed CloudEvents JSON document; they do not automatically produce the message or ticket format required by another platform. For Microsoft Teams, Google Chat, Jira, and similar tools, configure the receiving workflow to verify the BIMP request, select the required fields, and build the platform-specific message or ticket.

Worked example: notify reviewers about a Snooze Request

This example sends a Slack message whenever BIMP creates a new Snooze Request that needs review.

1. Create an incoming webhook for the required Slack channel by following Slack’s incoming webhook guide.
2. In BIMP, open Settings → Integrations → Webhooks.
3. Choose Add webhook.
4. Enter Snooze Requests to review as the webhook name.
5. Select Slack as the webhook type.
6. Paste the Slack incoming webhook URL into Endpoint URL.
7. Select the reviewer team as the audience.
8. Select Organization as the scope. Use a team scope instead if reviewers should receive only Snooze Requests routed to that team.
9. Clear the other event selections and select snooze request · created.
10. Create the webhook, then choose Test delivery from its row actions.

Test delivery

Test delivery sends a sample Policy Group update to confirm that the connection works. It does not create a Snooze Request or test your event selection.

When a new Snooze Request is created, Slack receives a message showing that the request was created, its BIMP reference, and an Open in BIMP button. Reviewers follow the link and complete the task through the normal BIMP review process.

To use the exact wording You have a Snooze Request to review, select Webhook instead and use a receiver or automation workflow to convert the event into a Teams, Google Chat, Slack, or ticketing-system message with that title.

Add a webhook

Choose Add webhook, then configure:

• Webhook name: a recognizable name such as Snooze Requests to review.
• Webhook type: Slack for a Slack incoming webhook, or Webhook for a signed generic integration.
• Endpoint URL: the HTTPS address that receives the event. Keep this URL secret when the destination embeds a token in it.
• Audience team: the BIMP team the destination is intended to notify. This identifies the audience; it does not give team members additional access.
• Scope: the BIMP activity that can trigger the webhook.
• Events: the changes that BIMP sends to the endpoint.

A scope can cover:

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

An organization scope receives matching events throughout the organization. A team scope receives matching events routed to that team. A Policy Group scope receives matching events for that Policy Group only.

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.

Configure the webhook content

The selected events and scope control which BIMP changes are sent. Choose only events that the receiving workflow needs. Available event families cover:

• Policy Group and policy mapping changes;
• Snooze Request creation, review, status changes, and reopening;
• remediation pull-request state changes.

The event list in Add webhook is the current source of truth. The same catalog is available from:

GET /api/v1/event-types

In BIMP you select the events and scope. In the receiving workflow you configure wording, formatting, ticket fields, labels, assignment, and priority. BIMP does not currently provide an editable message template. Content depends on the webhook type:

• Slack receives a concise BIMP-formatted message containing the event subject, action, reference, and an Open in BIMP link.
• Webhook receives a minimized CloudEvents JSON document. Your receiver decides how its fields become a chat message, ticket title, description, priority, labels, or assignment.

Every generic event includes common CloudEvents fields such as id, type, time, and subject, together with a data object. The data varies by event family. For example, a new Snooze Request awaiting review includes fields similar to:

{
  "type": "bimp.snooze_request.created",
  "subject": "exception_review/7bb8c046-8d5f-4b9e-a999-1014996d9c6d",
  "time": "2026-08-06T10:30:00.000Z",
  "data": {
    "snooze_request_id": "7bb8c046-8d5f-4b9e-a999-1014996d9c6d",
    "previous_status": null,
    "current_status": "pending",
    "action": "created",
    "repository_id": "f2521b23-a86a-426b-bbaf-cf5fa4c25e2e",
    "changed_at": "2026-08-06T10:30:00.000Z"
  }
}

The complete request also contains the CloudEvent ID, organization and resource references, correlation information, and schema metadata. It excludes provider credentials, email addresses, actor identifiers, branch and file paths, raw errors, and arbitrary internal metadata.

For a custom message, map the event type and data in the receiver. For example:

• when type is bimp.snooze_request.created, set the message title to You have a Snooze Request to review;
• include data.snooze_request_id as the BIMP reference; and
• add a link to the BIMP Tasks page.

In Jira, the same mapping could create a work item with the title Review BIMP Snooze Request, store the BIMP reference in its description, and use an existing Jira project, assignment, priority, and label configuration. Atlassian Automation exposes webhook data through its webhookData smart value.

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. Perform this verification in the first receiver you control before forwarding the content to another platform.

Send a test

Test delivery

Test delivery sends a sample Policy Group update to confirm that the connection works. It does not test the specifics of your event selection.

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. produced the intended message, ticket, or workflow action.

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.