Skip to content

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.

Each webhook receives the events you choose when you create it. webhook.test fires on demand from the Test button.

EventWhen it fires
work_item.waitingA work item now waits on a person: an ask, a judgment or a manual block.
work_item.doneA work item reached a terminal state.
change.openedColony opened a change on the code host.
change.mergedA change merged.
fault.raisedA fault opened, with its kind, scope and severity.
fault.resolvedA fault resolved by itself.
report.sealedA report sealed. The payload carries the complete report, its id and SHA-256.
cost.cap_reachedThe daily cost cap or a monthly ceiling was reached.
strategy.proposedThe Strategist proposed a strategy that waits for review.
strategy.appliedA strategy was applied by a person, by revert, or automatically.
webhook.testA synthetic test event sent via the Test button.

Every event payload except webhook.test carries event, orgId, tenant (id, externalId, name) and occurredAt. The rest depends on the event:

EventsAdditional fields
work_item.waiting, work_item.doneitem (repo, number, title, url), state and trait. work_item.waiting also carries the reason, when there is one, and the stewards.
change.opened, change.mergeditem, and change (number, url, plus mergedAt for change.merged).
fault.raised, fault.resolvedfault (id, kind, scope, repo, severity, firstSeenAt, plus resolvedAt for fault.resolved).
cost.cap_reachedfault.
report.sealedThe complete sealed report.
strategy.proposed, strategy.appliedstrategy (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.

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.

AliasNeutral event
issue.blockedwork_item.waiting
issue.donework_item.done
pr.openedchange.opened
pr.mergedchange.merged

A webhook subscribed to both an alias and its neutral name receives one delivery, with event set to the neutral name.

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.

Creating, editing, deleting, testing and replaying need the Operations grant, which owners and admins hold. Any member can list webhooks and view delivery history.

  1. 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 to report.sealed receives sealed reports for every tenant in the org; filter on tenant.id (or tenant.externalId) in the payload to route them. The old /settings/tenants/notifications link redirects to the selected tenant’s webhooks.
  2. Click Add webhook.
  3. Enter the URL — must start with https:// and be at most 2 048 characters.
  4. 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.
  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.

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.

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

HeaderValue
X-Colony-Signaturesha256=<hex> — HMAC-SHA256 of the raw request body, keyed with the signing secret
X-Colony-EventThe event type, e.g. report.sealed
X-Colony-Delivery-IdA 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.

  1. Open Operations → 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.

  1. Open Operations → Settings (Webhooks).
  2. In the webhook row, click History.
  3. The delivery history panel shows deliveries newest first, 25 per page. Click Load more to fetch older deliveries.

Each row shows:

ColumnDescription
EventThe event type that triggered the delivery
Statuspending — 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
AttemptsNumber of delivery attempts made so far
ResponseHTTP status code from the most recent attempt
CreatedWhen the delivery was first queued
DeliveredWhen the endpoint returned a successful 2xx response
  1. Open Operations → 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.

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:

RetryDelay (approximate)
1st retry30 seconds
2nd retry2 minutes
3rd retry10 minutes
4th retry1 hour
5th retry6 hours
6th retry24 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.