Webhooks

Outbound webhooks let you subscribe to Colony pipeline events and receive an HTTP POST to any https:// endpoint you control. Use them to pipe Colony signals into Slack, PagerDuty, internal dashboards, or any automation that consumes HTTP.

Events

Each webhook subscription receives notifications for the events you choose at creation time. The table below lists all event types. webhook.test fires on demand from the Test button; digest.daily is the only pipeline-driven event currently emitted. The eight pipeline and PR event types are reserved and do not yet produce deliveries.

Caution

The eight pipeline and PR events — issue.analyzed, issue.blocked, issue.done, pr.opened, pr.approved, pr.changes_requested, pr.merged, and cost.budget_warning — are reserved and do not currently fire. Subscriptions to these events are accepted in the UI, but no delivery will be queued until the emitters are wired to the pipeline runtime. Only digest.daily and webhook.test produce actual deliveries today.

Event	When it fires	Delivery
issue.analyzed	Colony finished analyzing an issue and produced a work plan — the issue is ready for development.	Reserved
issue.blocked	An issue has entered a blocked state (dependency-blocked, failure-blocked, or needs-clarification) and cannot progress without intervention.	Reserved
issue.done	An issue completed the full pipeline cycle: PR merged and state reached done. This is the canonical completion event.	Reserved
pr.opened	Colony opened a pull request for an issue. The PR URL and branch are included in the payload.	Reserved
pr.approved	A reviewer approved a Colony pull request. Fires on each approval event.	Reserved
pr.changes_requested	A reviewer requested changes on a Colony PR — the issue will be re-queued for development for revision.	Reserved
pr.merged	A Colony pull request was successfully merged to the target branch.	Reserved
cost.budget_warning	LLM token spend has approached or exceeded the configured cost threshold for the billing period.	Reserved
digest.daily	A scheduled daily operator digest: pipeline throughput, cost, blocked work, anomalies, and recommendations.	Active
webhook.test	A synthetic test event sent via the Test button.	Active

To configure the email delivery channel for the daily digest — recipients, send time, timezone, and quiet mode — see Digest Notifications.

Role requirements

Action	Owner	Admin	Member	Viewer
Create webhook	✓	✓	—	—
Edit or delete webhook	✓	✓	—	—
Send test delivery	✓	✓	—	—
Replay a delivery	✓	✓	—	—
List webhooks	✓	✓	✓	✓
View delivery history	✓	✓	✓	✓

Add a webhook

1. Open Settings → Webhooks.
2. Click Add webhook.
3. Enter the URL — must start with https:// and be at most 2 048 characters.
4. Choose a Format:
   • JSON payload (default) — Colony sends a JSON body signed with HMAC-SHA256. Use this for custom endpoints, automation platforms, and most integrations.
   • Slack message — Colony sends a Block Kit message formatted for Slack. The URL must be a hooks.slack.com incoming-webhook URL. No signature header is sent in this mode.
5. Check the events you want to receive. At least one event is required.
6. Optionally add a Description (up to 500 characters) to identify the webhook in the list.
7. Click Add webhook.

Caution

After creation, Colony shows the webhook signing secret once. Copy it immediately — it cannot be retrieved again. If you lose it, delete the webhook and create a new one.

Signing and verifying deliveries

When a JSON-format delivery is sent, Colony includes three headers:

Header	Value
X-Colony-Signature	sha256=<hex> — HMAC-SHA256 of the raw request body, keyed with the signing secret
X-Colony-Event	The event type, e.g. issue.done
X-Colony-Delivery-Id	A UUID that uniquely identifies this delivery attempt

The signing secret is a 64-character hex string (32 random bytes). To verify a delivery, compute HMAC-SHA256(secret, rawBody) and compare the result against the value in X-Colony-Signature after stripping the sha256= prefix. Always compare in constant time to prevent timing attacks.

Note

Slack-format webhooks do not include X-Colony-Signature, X-Colony-Event, or X-Colony-Delivery-Id. Slack’s own incoming-webhook URL provides the authentication boundary — Colony relies on the URL secret baked into the hooks.slack.com path.

Send a test delivery

1. Open Settings → Webhooks.
2. In the webhook row, click Test.
3. Colony queues a synthetic webhook.test delivery immediately. The test payload contains the event name, webhook ID, the user who triggered it, and a timestamp.
4. Click History on the same row to watch the delivery status update.

The test delivery follows the same retry and signing logic as a real event delivery.

Delivery history

1. Open Settings → Webhooks.
2. In the webhook row, click History.
3. The delivery history panel shows the most recent 100 deliveries, newest first.

Each row shows:

Column	Description
Event	The event type that triggered the delivery
Status	pending — queued, not yet attempted; retrying — at least one attempt failed, more scheduled; delivered — endpoint returned 2xx; failed — all attempts exhausted
Attempts	Number of delivery attempts made so far
Response	HTTP status code from the most recent attempt
Created	When the delivery was first queued
Delivered	When the endpoint returned a successful 2xx response

Replay a delivery

1. Open Settings → Webhooks.
2. Click History on the webhook row.
3. Find a delivery with status failed or retrying and click Replay.
4. Colony resets the delivery’s attempt counter to zero and queues it for immediate re-delivery.

Replaying does not create a new delivery record — it reuses the existing one, resetting its state to pending and scheduling it to fire right away.

Retry schedule and auto-disable

Colony attempts each delivery up to 7 times. If the initial attempt fails, the remaining retries are spaced with exponential back-off plus ±20% random jitter to avoid thundering-herd bursts:

Retry	Delay (approximate)
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
5th retry	6 hours
6th retry	24 hours

Each delivery attempt has a 30-second timeout. Payloads larger than 1 MB are dropped immediately without a retry attempt.

A delivery is counted as successful when the endpoint returns any 2xx HTTP status code.

Caution

Colony automatically disables a webhook after 20 consecutive delivery failures across all events. When a webhook is disabled, no new deliveries are queued until you re-enable it from Settings → Webhooks (click Edit and toggle it back on). The auto-disable event is recorded in the audit log.