A hook reacts to something happening in Coroid. You choose an event, write instructions in plain language, and the hook runs when the event fires.
Find them in the factory, under Automations.
Create one in New Work: choose Automation, then When something happens. New Work offers the GitHub events and Coroid's events. See Automations.
Events you can react to
A hook fires only for an event that something sends. Coroid sends most of the events below itself. A few are fired by your own systems. Any other event is reserved: the editor does not list it, and a new hook on one is refused. If a hook was saved on a reserved event, the editor and the list mark it as never firing; it is not deleted.
Events Coroid sends
| Category | Events |
|---|---|
| Task | Created, status changed, completed, failed |
| Agent | Started, completed, error |
| Repository | Commit pushed, branch created, pull request opened, updated or merged, issue opened, a comment that mentions Coroid |
| Sprint | Created, planning started, started, task added, task removed, review started, completed, cancelled |
| Plan | Phase started, completed, failed |
| Schedule | Run started, run completed, run failed |
| Report | Started, completed, failed |
| Quality | Check started, passed or failed; autonomously unresolved |
| Promotion | Requested, approved, rejected |
| Release | Created, candidate changed, notes changed, notes approved, scope changed, checklist completed, gate evaluated, gate overridden, approved, published, rolled back |
| Deployment | Queued, running, succeeded, failed, cancelled, attested manually, rollback attested manually, health check passed, health check failed |
| Sync | External source updated |
| Slack and Telegram | A message that matches the automation's filter |
Events your own systems fire
| Category | Events |
|---|---|
| Analysis | Dependency found, security issue found, analysis completed |
| External deployment | Started, completed, failed |
Coroid does not send these. A CI pipeline, a scanner or another system of yours
fires the hook by its id: it calls POST /api/v1/organizations/hooks/:id/dispatch
with the key of a service account
that has the hooks:dispatch scope. The hook runs for the event it was saved
on. The editor lists these events under "Fired by your own systems".
Reserved events
These are not sent or fired yet, so the editor does not offer them:
| Category | Events |
|---|---|
| Task | Phase changed |
| Agent | Iteration, tool called |
| Plan | Created, phase completed, final review started, final review completed, before the plan's pull request |
| Schedule | Created, activated, paused |
| Sprint | Planning completed, task completed, scope changed |
| Release | Staged, validated |
| Promotion | Before the promotion's pull request |
| Quality | Check unavailable; repair started or attempted; revalidation started; consensus reached |
When work starts and ends
Plans, schedules, reports, Quality checks, promotions and releases send an event when they start and an event when they end. A hook can react to how the work ended, and a system of yours can measure how long it took.
| Work | Starts | Ends |
|---|---|---|
| Plan | Phase started: the first one is sent when the plan's execution starts | Completed, failed |
| Schedule | Run started | Run completed, run failed |
| Report | Started | Completed, failed |
| Quality check | Check started | Passed, failed, autonomously unresolved |
| Promotion | Requested | Approved, rejected |
| Release | Created | Published, rolled back |
Each of these events records the time it happened in occurredAt. An event
that reports how the work ended also records when the work started in
startedAt, and how long it took in durationMs. That startedAt is the
occurredAt of the start event, so the two always match. Time the work spent
paused counts toward the duration.
Each event is sent once, when the change is saved. A change that is undone sends nothing, and a retry sends nothing twice. An end is sent only for work that started: a schedule's dry run sends nothing, and neither does a report cancelled before it started.
What each event carries, besides the times:
| Event | Sent when | Fields |
|---|---|---|
| Plan phase started | The plan's execution starts (its first phase), and later whenever another phase's first task starts | planId, plan (id, title), phase (id, sequence, title), firstPhase, executionStartedAt |
| Plan completed or failed | The plan's execution ends. A plan that fails while it is being planned sends neither | planId, plan, status, executionStartedAt |
| Schedule run started | A schedule run starts | scheduleId, runId, schedule (id, name), run (trigger reason, parent run) |
| Schedule run completed or failed | The run ends | The same fields, status, and tasksCreated or error |
| Report started | A report starts generating. Pausing and resuming keep the same start | reportId, report (id, type, title) |
| Report completed or failed | The report is saved, or it fails or is cancelled | The same fields, and tokensUsed, costUsd and hasActionableFindings, or error |
| Quality check started | A Quality check starts | qualityRunId, check (subject, trigger, policy version, commit) |
| Quality check passed or failed | The check reaches its decision | The same fields, decision, redoCause, failedExpectationIds |
| Quality autonomously unresolved | Coroid stops trying to repair what a check found | qualityRunId, workItemType, workItemId, reason |
| Promotion requested | A promotion is created | promotionId, laneId, promotion (title, status, branches, pull request) |
| Promotion approved | The promotion is merged: approved in Coroid, force merged, merged at the provider or shipped in a release | The same fields, approval, approvedBy, forceReason |
| Promotion rejected | A reviewer requests changes | The same fields, reason, requestedBy, comment |
| Release published | The release's first production deployment succeeds | releaseId, version, commitSha |
| Release rolled back | A rollback replaces the release in an environment | releaseId, version, rolledBackToReleaseId |
Events about work in a project also carry projectId, so a hook limited to one
project fires only for that project. If a hook created the work, these events
count toward that hook's chain depth.
Triggers and destinations
Every automation has a trigger source, where its events come from, and a destination, which decides what happens when one fires. Two of the destinations turn an event into work.
| Trigger source | Events |
|---|---|
| Workflow event | Events in Coroid, as in the table above |
| GitHub | Pull request opened, updated or merged; issue opened; a comment that mentions Coroid |
| Slack | A message that matches the automation's filter |
| Telegram | A message that matches the automation's filter, such as one that starts with /coroid |
| Jira | A new issue |
| Destination | What happens |
|---|---|
| Hook | Runs your instructions, read-only, as described on this page |
| Qualify work | Files the event as a request. Once Qualification passes it, Coroid creates the work |
| Coroid Check | Retired. Coroid Review of every pull request is set in Quality Control; existing automations were paused |
GitHub events need the GitHub App. A comment that mentions Coroid counts only when its author has write access to the repository. See GitHub.
A task from Qualify work starts on its own only when the event's author is trusted: the author of a GitHub pull request, issue or comment who has write access to the repository. Slack, Telegram and Jira authors are never trusted, so their tasks wait for someone to start them. See When the work starts.
New Jira issues reach Coroid only through its Jira webhook. It accepts only deliveries signed with the webhook secret set up for Coroid, only for new issues, and only when the issue's Jira project key matches a Coroid project. On coroid.ai the Jira webhook is not set up yet, so a Jira trigger receives no events; import Jira issues instead. Where the webhook is set up, a new issue goes to the automations on the Jira trigger, such as the Jira request source in Quality Control, which files issues of the types and priorities you choose for Qualification. With no automation on the trigger, a new issue files nothing. Work from Jira never starts on its own. See Issue trackers.
Read-only by default
Hooks analyse and report. They can create follow-up work; they do not modify your code directly.
That default is what makes them safe to adopt. An automation that edits code in response to an event is acting at the moment least likely to be supervised. A hook that opens a task produces the same outcome through the normal path — specification, plan, verification, review, pull request.
- ScheduleTime
- Event automationSomething happens
An ordinary task
Specification, plan, build, verify, review. Uses an agent slot; give it a lower priority.
P2P3A pull request
It cannot merge itself or commit to your base branch.
You approve
Writing good instructions
Hook instructions are processed by a model, so they read like instructions to a colleague rather than code. The quality bar is the same as for a specification: say what to look at, what matters, and what to do.
Be specific about the "do nothing" case. Without it, a hook will find something to say every time it runs, and hooks that always fire are hooks people stop reading.
Guardrails
Three protections exist because event-driven automation fails in predictable ways:
Rate limits. Per minute, per hour and per day, configurable per hook. A hook on a high-frequency event can otherwise fire hundreds of times during a busy merge.
Chain depth. Hooks can trigger events that trigger hooks. A maximum chain depth stops that becoming a loop.
Tool permissions. What a hook may reach is controlled — read-only access, MCP calls and task creation are separately governed.
Permissions
Only owners and admins can create, change, test or delete a hook; all members can see hooks and their execution history. Given a hook runs with organization-level reach, that asymmetry is deliberate.
Watching them
Each hook's page in the factory lists its runs and what it did over the last 30 days: runs, failures and cost. Every automation run is also in Settings → Activity, filtered by Automation. Check its runs after enabling a new hook — the failure mode is not an error, it is firing constantly and producing nothing anyone acts on.
Hooks and schedules
| Mechanism | Triggered by |
|---|---|
| Hook | A platform event |
| Schedule | Time |
Both are automations, listed together in the factory. See Automations.