Skip to content
Coro Docs

Webhooks & external events

Coro jobs routinely park waiting for merges, approvals, tracker comments, or plugin-specific signals. Reliable automation depends on inbound events — see /concepts/job-lifecycle/ (or the park/resume discussion in /concepts/runner-spec/) alongside this guide.

What fires webhooks

Built-in SCM plugins (GitHub, Bitbucket, GitLab…) and trackers (for example Jira) expose normalised payloads the runner consumes. Plugins declare a webhook descriptor:

  • algorithm — hmac-sha256, hmac-sha1, or none.
  • header / format — how the SCM signs the POST body (X-Hub-Signature, x-hub-signature-256, etc.).
  • Optional pathSuffix for distinguishing multiple ingress routes behind the cloud edge.

Hybrid cloud stores per-team webhook rows (tenant_plugin_webhooks), loads secrets from Postgres, and verifies raw body MAC comparisons before emitting event:pluginWebhook frames to connected runners (/guides/hybrid-mode/).

SCM webhooks vs tracker webhooks

SourceTypical eventRunner effect
Git hostPR approved, merged, commentResume review / evaluation phases awaiting pull_request:*.
Issue trackerComment, assignment, epic linkPlanner / campaign agents receive tracker prompts.

Misconfigured tracker credentials downgrade to stubs — behaviours fall back documented in /concepts/architecture/.

HMAC verification (team mode)

Teams should treat webhook secrets like API keys:

  1. Provision secret in SCM UI → store encrypted-at-rest mirror in cloud DB via dashboard automation (exact UI depends on installer).
  2. Rotate with dual-record overlap to avoid wedging parked jobs stuck awaiting dead endpoints.
  3. When algorithm is none (classic Jira webhook variant relies on opaque URL secrets), keep URLs unguessable and rotate alongside PATs.

Solo / polling fallback

Without cloud forwarding, parked jobs may rely on coro resume, coro message, or periodic SCM polls (plugin-dependent). Operational runbooks must state explicit SLAs: “solo developers must leave coro start alive or resume manually”. Encourage migrating teams to hybrid once more than one person depends on merges.

Manual escape hatches (coro resume --job …) remain available for tabletop exercises (/reference/cli/ when published).

Configuration checklist