Webhooks

What this means

Webhooks let external tools notify Bilbis when something changes.

Instead of a user manually creating every pipeline, GitLab, GitHub, or Jira can send an event to Bilbis. Bilbis verifies the event with a shared secret or signature, then decides whether the event should start or resume a pipeline.

When to use it

Use webhooks when you want Bilbis to react to:

A Jira issue moving into a status such as Ready for AI.
A Jira comment that answers a pending clarification.
A GitLab issue or merge request event.
A GitHub issue, issue comment, pull request, or pull request comment event.
A GitLab/GitHub label that should trigger a product-specific pipeline.

Before you start

You need:

Owner or admin access in Bilbis.
A configured Git provider or Jira integration.
A product and at least one repository for Git webhooks.
Access to the provider's webhook settings.
A long random secret value for each webhook configuration.

Webhook types

Webhook	Where it is configured	What it can do
Jira	Settings -> Integrations -> Jira, or product Jira override	Trigger pipelines from issue status changes and resume clarification pipelines from comments.
GitLab	Product detail -> GitLab / GitHub webhook, then GitLab project settings	Trigger or resume pipelines from GitLab events.
GitHub	Product detail -> GitLab / GitHub webhook, then GitHub repository settings	Trigger or resume pipelines from GitHub events.

GitLab and GitHub product webhook fields

These fields live on the product detail page.

Field	What it means	Default
Trigger labels	Labels that tell Bilbis an event should start a pipeline for this product. They must match exactly.	`ai-ready`, `bilbis`
Enable webhook for this product	Turns webhook-triggered pipelines on or off for this product.	Off
Default engine	Engine used for webhook-triggered pipelines when the event does not specify one.	Claude Sonnet
Default task type	Task type used for webhook-triggered pipelines.	Feature
Default budget cap	Maximum spend for webhook-triggered pipelines.	`$5`
GitLab webhook URL	Bilbis endpoint to paste into GitLab.	Shown in the UI
GitHub webhook URL	Bilbis endpoint to paste into GitHub.	Shown in the UI
Signing secret	Secret the provider sends so Bilbis can verify the event.	Empty until configured

Endpoint reference

Use the URLs shown in Bilbis when possible. Production endpoints are:

https://api.bilbis.ai/api/v1/webhooks/jira
https://api.bilbis.ai/api/v1/webhooks/gitlab
https://api.bilbis.ai/api/v1/webhooks/github

Provider authentication differs:

Provider	Secret or signature
Jira	Custom header: `X-Jira-Webhook-Token: <secret>`
GitLab	Secret token header: `X-Gitlab-Token: <secret>`
GitHub	HMAC signature header created by GitHub from the configured secret.

Configure a Jira webhook

Open Settings -> Integrations -> Jira in Bilbis.
Save a webhook secret.
Copy the Jira webhook URL.
In Jira, create a webhook.
Add the custom header X-Jira-Webhook-Token with the Bilbis webhook secret.
Subscribe to issue updated and comment created events.
Save the Jira webhook.

Configure a GitLab webhook

Open the product in Bilbis.
Open the GitLab / GitHub webhook card.
Set trigger labels and pipeline defaults.
Create a long random signing secret and save it in Bilbis.
Copy the GitLab webhook URL.
In GitLab, open the project webhook settings.
Paste the Bilbis URL.
Paste the signing secret as the GitLab secret token.
Subscribe to the events your workflow needs, such as issues, comments, and merge requests.
Save the webhook.

Configure a GitHub webhook

Open the product in Bilbis.
Open the GitLab / GitHub webhook card.
Set trigger labels and pipeline defaults.
Create a long random signing secret and save it in Bilbis.
Copy the GitHub webhook URL.
In GitHub, open the repository webhook settings.
Paste the Bilbis URL.
Set the content type to JSON.
Paste the signing secret.
Subscribe to the events your workflow needs, such as issues, issue comments, and pull requests.
Save the webhook.

What happens next

When a provider sends an event, Bilbis first verifies that the event is authentic. If the secret or signature is missing or wrong, Bilbis rejects the event.

If the event is valid, Bilbis checks whether the event matches your trigger rules. Matching events can start a new pipeline or resume a pipeline that is waiting for clarification.

Problems and fixes

Problem	What to check
Provider delivery shows unauthorized	Confirm the secret in the provider matches the secret saved in Bilbis.
GitHub delivery fails signature validation	Confirm the GitHub secret is copied exactly and the webhook content type is JSON.
Event reaches Bilbis but no pipeline starts	Check that the label or Jira status exactly matches the configured trigger.
Webhook starts pipelines for the wrong product	Check product mappings in Jira or product-level webhook config for Git providers.
Comment does not resume a pipeline	Confirm the pipeline is waiting for clarification and the webhook subscribes to comment events.
Users are unsure which budget applies	Webhook-triggered pipelines use the product webhook default budget unless the event provides a more specific value.

On this page