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 internal dashboards, automation platforms, or any endpoint that consumes signed JSON over HTTP. To post lines to a channel, connect chat instead.
Events
Section titled “Events”Each webhook receives the events you choose when you create it. webhook.test fires on demand from the Test button.
| Event | When it fires |
|---|---|
work_item.waiting | A work item now waits on a person: an ask, a judgment or a manual block. |
work_item.done | A work item reached a terminal state. |
change.opened | Colony opened a change on the code host. |
change.merged | A change merged. |
fault.raised | A fault opened, with its kind, scope and severity. |
fault.resolved | A fault resolved by itself. |
report.sealed | A report sealed. The payload carries the complete report, its id and SHA-256. |
cost.cap_reached | The daily cost cap or a monthly ceiling was reached. |
strategy.proposed | The Strategist proposed a strategy that waits for review. |
strategy.applied | A strategy was applied by a person, by revert, or automatically. |
webhook.test | A synthetic test event sent via the Test button. |
Payloads
Section titled “Payloads”Every event payload except webhook.test carries event, orgId, tenant (id, externalId, name) and occurredAt. The rest depends on the event:
| Events | Additional fields |
|---|---|
work_item.waiting, work_item.done | item (repo, number, title, url), state and trait. work_item.waiting also carries the reason, when there is one, and the stewards. |
change.opened, change.merged | item, and change (number, url, plus mergedAt for change.merged). |
fault.raised, fault.resolved | fault (id, kind, scope, repo, severity, firstSeenAt, plus resolvedAt for fault.resolved). |
cost.cap_reached | fault. |
report.sealed | The complete sealed report. |
strategy.proposed, strategy.applied | strategy (repo, version, and summary: the track changes, such as “1 track created, 1 retired”). strategy.applied also carries appliedBy: { name } for a person, or null when it applied automatically. |
Colony does not send a backlog when events are first switched on for a tenant: only transitions and changes after that point produce deliveries.
Older names
Section titled “Older names”Four older names stay as aliases for the neutral event. A webhook subscribed to an alias receives the neutral event’s delivery with event set to the alias it subscribed to, so existing consumers keep working unchanged.
| Alias | Neutral event |
|---|---|
issue.blocked | work_item.waiting |
issue.done | work_item.done |
pr.opened | change.opened |
pr.merged | change.merged |
A webhook subscribed to both an alias and its neutral name receives one delivery, with event set to the neutral name.
Retired names
Section titled “Retired names”issue.analyzed, pr.approved, pr.changes_requested and cost.budget_warning were never emitted and have no neutral counterpart. The migration removed them from existing webhooks, and disabled any webhook left with no event. Creating or updating a webhook with one of these names is refused with 400.
Email delivery of sealed reports is a per-person subscription; see Report delivery.
Role requirements
Section titled “Role requirements”Creating, editing, deleting, testing and replaying need the Operations grant, which owners and admins hold. Any member can list webhooks and view delivery history.
Add a webhook
Section titled “Add a webhook”- Open Operations → Settings (Webhooks) (
/operations/settings#webhooks). Webhooks belong to your organization, not to a tenant, so the same list appears under every tenant. A webhook subscribed toreport.sealedreceives sealed reports for every tenant in the org; filter ontenant.id(ortenant.externalId) in the payload to route them. The old/settings/tenants/notificationslink redirects to the selected tenant’s webhooks. - Click Add webhook.
- Enter the URL — must start with
https://and be at most 2 048 characters. - Colony sends a JSON body signed with HMAC-SHA256. Use it for custom endpoints, automation platforms, and most integrations. To post lines to a channel, connect chat instead.
- Check the events you want to receive. At least one event is required.
- Optionally add a Description (up to 500 characters) to identify the webhook in the list.
- Click Add webhook.
The older Slack format
Section titled “The older Slack format”Webhooks created with the Slack message format (shown as “Slack message (older format)”) keep delivering until someone deletes them, and can still be edited, disabled and re-enabled. New ones are refused with 400: “Connect chat in Account › Connections to post lines to a channel.” Connect chat instead; see Chat.
Signing and verifying deliveries
Section titled “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. report.sealed |
X-Colony-Delivery-Id | A UUID that identifies this delivery. Retries and replays of the same delivery send the same value, so you can use it to deduplicate |
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.
Send a test delivery
Section titled “Send a test delivery”- Open Operations → Settings (Webhooks).
- In the webhook row, click Test.
- Colony queues a synthetic
webhook.testdelivery immediately. The test payload contains the event name, webhook ID, the user who triggered it, and a timestamp. - 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
Section titled “Delivery history”- Open Operations → Settings (Webhooks).
- In the webhook row, click History.
- The delivery history panel shows deliveries newest first, 25 per page. Click Load more to fetch older deliveries.
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, the payload was over 1 MB, or the webhook was disabled or deleted before the attempt |
| 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
Section titled “Replay a delivery”- Open Operations → Settings (Webhooks).
- Click History on the webhook row.
- Find a delivery with status
failedorretryingand click Replay. - 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
Section titled “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.