# Webhooks

Source: https://docs.coderhelm.com/api/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](/api/authentication#ci-uploads)) |

All paths are on `https://api.coderhelm.com`.

## GitHub [#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 [#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 [#jira-webhook]

If you can't install the Jira app, create a plain Jira webhook (see [Connect Jira](/getting-started/jira)). Its URL holds a token generated for your team:

```txt
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 `comment` retries 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 starting `coderhelm:`), 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`:

```json
{
  "webhookEvent": "jira:issue_updated",
  "issue": { "key": "WEB-42", "fields": { "labels": ["coderhelm"] } },
  "coderhelm": { "repo_owner": "your-org", "repo_name": "web" }
}
```

## Alerts from AWS [#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.