Webhooks

Deliver real-time event notifications to external systems.

What Are Webhooks?

Webhooks are HTTP POST notifications that the platform sends to external URLs when events occur in your Git repositories. Instead of polling the platform to check whether something happened, your external systems receive a notification the moment it happens. This enables real-time integrations with build systems, chat tools, deployment platforms, monitoring services, and anything else that can receive HTTP requests.

Webhooks use a GitHub-compatible payload format, which means most tools and libraries that already integrate with GitHub can work with Bosca Git webhooks with minimal or no modification.

Supported Events

You choose which events trigger webhook deliveries. Only the events you subscribe to will generate notifications, so you can keep the volume manageable and targeted:

Configuring a Webhook

Each webhook has a few core settings:

• Target URL. The HTTP endpoint where the platform sends POST requests. This is typically a URL provided by your external service — a Slack incoming webhook URL, a CI system's trigger endpoint, or a custom server you control.
• Shared secret. A secret string used to sign each webhook payload with HMAC-SHA256. The receiving system can verify this signature to confirm that the request genuinely came from your Bosca instance and was not tampered with in transit. The signature format is compatible with GitHub's webhook signature verification, so libraries built for GitHub webhook validation work here too.
• Event selection. Choose which events trigger deliveries. You can select individual events or subscribe to all events.
• Active or inactive. Toggle a webhook on or off without deleting it. This is useful for temporarily disabling a webhook during maintenance on the receiving system, or for keeping a webhook configured but dormant until you are ready to enable it.

Payload Signing and Verification

When you configure a shared secret, every webhook delivery includes a signature header. The platform computes an HMAC-SHA256 hash of the request body using your secret and includes it in the delivery headers. The receiving system should compute the same hash using its copy of the secret and compare the two values. If they match, the payload is authentic and unmodified.

This verification step is important for security. Without it, anyone who discovers your webhook URL could send forged payloads that your system would process as legitimate events. Always configure a shared secret and always verify signatures on the receiving end.

Delivery Tracking

Every webhook delivery is logged by the platform, giving you full visibility into what was sent and how the receiving system responded. Each delivery record includes:

• Event type — Which event triggered the delivery.
• Request payload — The full JSON body that was sent.
• Response status code — The HTTP status code returned by the receiving system.
• Response body — The response content returned by the receiving system.
• Retry count — How many times the delivery was attempted if the initial attempt failed.
• Success or failure — Whether the delivery was ultimately successful.

This delivery log is invaluable for debugging integration issues. If a webhook is not working as expected, you can review the delivery history to see whether the request was sent, what the payload looked like, and how the receiving system responded.

GitHub-Compatible Payload Format

Bosca Git webhooks use a payload format that is compatible with GitHub's webhook payloads. This compatibility is intentional — it means the large ecosystem of tools, libraries, and services that already work with GitHub webhooks can integrate with Bosca Git with minimal effort.

If your team already uses tools that consume GitHub webhook events — CI/CD platforms, Slack bots, deployment automation, security scanners — there is a good chance they will work with Bosca Git webhooks by simply pointing them at your Bosca instance instead of GitHub.

Common Use Cases

Webhooks are a general-purpose integration mechanism. Here are some of the most common ways teams use them:

Triggering External CI/CD

While Bosca Git includes built-in CI/CD pipelines, some teams prefer to use external CI systems like Jenkins, CircleCI, or Buildkite. A push webhook can trigger builds in these systems whenever code is pushed. The external CI system processes the build and can report status checks back to the repository.

Chat Notifications

Connect push, pull request, and review events to Slack, Microsoft Teams, or Discord to keep your team informed in the channels where they already communicate. When a PR is opened, a review is submitted, or a pipeline fails, the relevant channel gets an automatic notification.

Deployment Automation

Use tag creation webhooks to trigger deployment workflows. When a release tag is pushed, the webhook notifies your deployment system, which pulls the tagged version and deploys it to the target environment. Combined with branch protection on the main branch, this creates a controlled release pipeline.

Audit Logging

Send all Git events to a centralized logging or SIEM system for compliance and security auditing. Every push, branch creation, PR merge, and permission change is captured as a webhook delivery, providing a complete audit trail that lives outside the platform itself.

Custom Integrations

Build your own integration endpoints that respond to Git events. Update a project dashboard when PRs are merged. Notify stakeholders when changes land in a release branch. Synchronize repository state with an external project management tool. Webhooks give you a real-time event stream that you can process however your workflow requires.