Webhooks
The webhooks CoderHelm receives from GitHub, Jira and AWS, how each is verified, and what each event does.
CoderHelm receives events on four kinds of webhook. Every one is verified before anything happens; an unverified request is refused and changes nothing.
| Path | From | Verified by |
|---|---|---|
POST /webhooks/github | The CoderHelm GitHub App | X-Hub-Signature-256 HMAC |
POST /webhooks/jira | The CoderHelm Jira app | The team's Jira app secret in the body |
POST /webhooks/jira/:token | A Jira webhook you create | The per-team token in the URL, and optionally X-Hub-Signature |
POST /webhooks/alerts/sns | An AWS SNS topic | The SNS message signature |
POST /webhooks/ci/tests/results | GitHub Actions | A GitHub OIDC token (see Authentication) |
All paths are on https://api.coderhelm.com.
GitHub
GitHub sends every event of the CoderHelm App here. You don't set this up; installing the app does.
Each request is signed with the app's webhook secret: X-Hub-Signature-256: sha256=<hex> is an HMAC-SHA256 of the raw body, compared in constant time. A missing or wrong signature gets 401. The event type comes from X-GitHub-Event, and the body must name an installation.
| Event | What CoderHelm does |
|---|---|
installation, installation_repositories | Links the installation and its repositories to your team. |
issues (assigned to the bot, or labeled coderhelm) | Starts a run. |
issue_comment, pull_request_review_comment | /coderhelm or @coderhelm starts a run or sends feedback; @coderhelm re-review and questions go to the reviewer. |
pull_request | Reviewer triggers (the review label, new pushes), review requests, and merge tracking. |
pull_request_review | Feedback on CoderHelm's pull requests. |
push | A tag writes release notes. A push to the default branch syncs skills, proposes team tools from .coderhelm/tools/ and updates the code graph. |
check_run, check_suite, workflow_run | Records CI results and resumes CI fixing. |
repository | Follows renames, archives and deletes. |
Other events are accepted with 200 and ignored. An event from an installation that isn't linked to a team is also accepted and ignored.
Jira app
The CoderHelm Jira app (an Atlassian Forge app) posts events here. The body carries your team id and the secret shown on the Jira page of the dashboard, under coderhelm.team_id and coderhelm.forge_secret. A wrong secret gets 403.
Jira webhook
If you can't install the Jira app, create a plain Jira webhook (see Connect Jira). Its URL holds a token generated for your team:
https://api.coderhelm.com/webhooks/jira/<token>An unknown token gets 401. If you also generated a secret, each request must carry X-Hub-Signature: sha256=<hex>, an HMAC-SHA256 of the body with that secret.
What happens with each event:
- An event whose name contains
commentretries a failed run, or sends feedback to a run that already opened a pull request. - Any other issue event starts a run when the ticket has the label
coderhelm(or one startingcoderhelm:), or is assigned to a user whose name contains "CoderHelm", in a project you switched on.
To pin a ticket to a repository from an automation, add repo_owner and repo_name to the payload, at the top level or under coderhelm:
{
"webhookEvent": "jira:issue_updated",
"issue": { "key": "WEB-42", "fields": { "labels": ["coderhelm"] } },
"coderhelm": { "repo_owner": "your-org", "repo_name": "web" }
}Alerts from AWS
CoderHelm can turn an alarm into a fix. Subscribe CoderHelm to an SNS topic with an HTTPS subscription to https://api.coderhelm.com/webhooks/alerts/sns, and add the topic under Alert routes in the dashboard.
- Every message's SNS signature is checked (signature versions 1 and 2), and the signing certificate must come from SNS. Anything else gets
403. - The subscription is confirmed automatically once the topic has an enabled route. Messages from topics without a route are accepted and ignored.
- Accepted messages: CloudWatch alarm notifications, AWS Chatbot custom notifications, EventBridge events and plain text.
A message that matches one of the route's rules becomes a run that opens a pull request. Other messages are posted to your team's Slack or Teams channel. Every alert is listed on the Alerts page with what CoderHelm did with it.
There are no inbound webhooks for Slack or Teams; CoderHelm only sends messages to them.