Webhooks

Webhooks post an HTTP request to a URL you choose whenever something happens in a project — a deploy finishes, a service crashes, the autoscaler moves. Point them at your own endpoint, or straight at a Slack or Discord incoming webhook.

Events

Event	Fires when
`deployment.started`	A deploy begins
`deployment.completed`	A deploy finishes successfully
`deployment.failed`	A deploy fails (and is rolled back)
`service.stopped`	A service is stopped
`service.crashed`	A service exits unexpectedly
`scaling.event`	The autoscaler changes replica count
`alert.triggered`	A monitoring alert fires

A webhook with no events selected receives all of them.

From the dashboard

Open a project and go to its Webhooks tab.
Click Add webhook and paste the destination URL.
Choose the events to subscribe to (or leave empty for all).
Optionally set a signing secret (see below), then save.

The webhook’s recent deliveries are listed with each attempt’s response status, so you can confirm your endpoint is receiving events.

From the CLI

# Subscribe to every event
bitsreef webhooks add https://example.com/hooks/bitsreef my-project

# Only specific events, with a signing secret
bitsreef webhooks add https://example.com/hook my-project \
  -e deployment.failed -e service.crashed --secret s3cr3t

bitsreef webhooks list my-project

# Change events, secret, or active state
bitsreef webhooks update 12 my-project -e deployment.completed --inactive

bitsreef webhooks remove 12 my-project

Request format

Each delivery is a POST with a JSON body and these headers:

Header	Value
`Content-Type`	`application/json`
`X-BitsReef-Event`	the event type, e.g. `deployment.completed`
`X-BitsReef-Signature`	`sha256=<hmac>` — present only when a secret is set

When you set a secret, BitsReef signs the raw request body with HMAC-SHA256 and sends the hex digest in X-BitsReef-Signature. Verify it before trusting a payload:

import hashlib, hmac

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Destination URLs are validated against an SSRF guard, so a webhook cannot be pointed at an internal or private address. Deliveries that return a non-2xx status are marked failed and retried.