# Platform deploy webhooks and GitHub deployments

Tell Bucker what your hosting platform did, so an issue shows what changed just before it
started. A deploy, a restart, a scale change or a rollback on Vercel, Render, Railway, Heroku or
Netlify becomes a **change event** in the project, and a deploy also becomes a **deploy** on the
release it shipped. GitHub's *deployments* do the same from your repository.

This is not the log drain (that carries logs; see [Log drains](log-drains.md)). It carries
changes.

## What each platform becomes

| Platform | Reported | Becomes |
| --- | --- | --- |
| Vercel | `deployment.created`, `.succeeded` / `.ready`, `.error` / `.canceled` | a deploy: started, succeeded, failed |
| Render | `deploy_ended` | a deploy: succeeded, failed (`deploy_started` is not read: Render's payload names the event, not the deploy, so a start could never be matched to its end) |
| Render | `server_failed`, `server_restarted` | a **restart** |
| Render | `autoscaling_*`, `instance_count_changed` | a **scale** change |
| Render | `service_suspended` / `_resumed`, `maintenance_*` | a **host event** |
| Railway | a deployment moving through building, success, failed | a deploy |
| Railway | a crashed deployment | a **restart** |
| Heroku | a release: pending, succeeded, failed | a deploy |
| Heroku | a release whose description is `Rollback to vN` | a **rollback** (and no deploy, so a chart draws one "we went back" marker) |
| Heroku | a formation quantity change | a **scale** change |
| Heroku | a formation size change | a **machine config** change |
| Heroku | a dyno restarting, a dyno crashed | a **restart**, a **host event** |
| Netlify | a deploy: building, ready, error | a deploy |
| GitHub | `deployment` and `deployment_status` | a deploy (below) |

Anything else a platform sends is answered `200 ignored`, and a payload Bucker cannot read is too:
a platform that gets an error for a payload shape it did not expect turns the hook off, and then
the signal is gone. A delivery older than 48 hours is `200 stale` and changes nothing.

## Setting a platform up

Open **Settings, Integrations** and press **Show webhook URLs** on *Platform deploy webhooks*,
then pick the project. It needs write access to the project, because the secrets are not public,
and the look is recorded in the audit log.

Every URL has the shape `https://<ingest host>/webhooks/platforms/<platform>/<project id>?sentry_key=<DSN public key>`.
The key names the project, so disabling or revoking that DSN key stops the webhook. A delivery
signed for one project and sent to another project's URL is refused.

**Where each secret comes from.** Two kinds, because the platforms differ:

- **Railway and Heroku** let you choose the secret (Railway as a custom header on the webhook,
  Heroku with `heroku webhooks:add --secret`), so Bucker derives one for the project and shows it
  on the card, like a DSN. Anyone who holds a derived secret can add deploy markers to the
  project, so treat it like a DSN. It changes if the DSN key is rotated, and the card shows the
  new value.
- **Vercel, Render and Netlify** show the secret in their own webhook form (Vercel and Render
  create it and do not take a chosen one). Add it once under **Settings, Connections** (provider
  Vercel, Render or Netlify, purpose *signal*, optionally for one project). It is sealed and
  never shown again, and the card says only whether one is in place. Until then every delivery
  from that platform is refused.

**How each is checked.** Over the exact bytes received, before anything is read:

| Platform | Scheme |
| --- | --- |
| Vercel | `x-vercel-signature`: hex HMAC-SHA1 of the body |
| Render | Standard Webhooks: `webhook-id`, `webhook-timestamp` (within five minutes) and `webhook-signature` |
| Heroku | `Heroku-Webhook-Hmac-SHA256`: base64 HMAC-SHA256 of the body |
| Netlify | `x-webhook-signature`: a JWS (HS256) whose claims name Netlify and the body's SHA-256 |
| Railway | no signature exists: the secret travels in the `x-bucker-webhook-secret` header and a delivery without it is refused. Add it as a custom header in Railway's webhook form |

Every refusal is the same `403 Invalid webhook signature` after the same computation, whether the
header was missing, malformed, wrong, signed for another project, or no secret exists. A refused
delivery writes nothing.

## One deploy, however many sources

A Vercel webhook, GitHub's `deployment_status` and `bucker deploys new` can all report the same
deploy. Bucker keeps **one deploy and one change event** and lists every source on it. They are the
same deploy when they share the **provider deployment id**, or else the **commit SHA**, and the
**environment** (compared after normalizing: `Production – shop`, `PRODUCTION` and `production`
are one environment).

- A platform report finds the release by the commit: if you registered `1.4.0` at that commit with
  the CLI, the platform reports land on `1.4.0`. With no such release the commit SHA becomes the
  release version. If you register a release at that commit **after** a platform has already
  reported it, the CLI's version is a second release; register releases before the deploy.
- The first report that carries an outcome settles the deploy. A later report that disagrees does
  not rewrite it: it is stored beside the outcome and the deploy is marked contradicted.
- Two platform deployments of one commit are two deploys. A redelivery of one is not.
- Two services that shipped one commit stay two deploys.

## GitHub deployments

Bucker reads `deployment` and `deployment_status` for a repository whose connection holds the
**Deployments** consent (`deployments:read`). `success` is a succeeded deploy, `failure` and
`error` a failed one, `pending`, `queued` and `in_progress` a started one. `inactive` says the
environment's previous deployment was replaced: it adds a source to a deploy Bucker already knows
and never creates one, so replacing an old deployment cannot look like a rollback.

A repository connected before this consent existed is left untouched until a person accepts it
again on **Settings, Repos**, and the GitHub App needs the **Deployments: read** permission and
the `deployment` and `deployment_status` event subscriptions. The webhook secret is the
repository's own.

## What an agent sees

Provider text (a service name, a failure reason, a release description) is treated as data. It is
passed through the infrastructure field policy and your organization's scrub rules, clipped, and
stored on a change event marked untrusted; a deploy event carries no provider text at all. It
reaches root-cause analysis only as a labelled, scanned change correlation, never verbatim.

## Not covered yet

Fly machine polling, cloud configuration events (CloudTrail, Event Grid, Admin Activity) and the
Cloudflare relay are not part of this. Netlify and Vercel deploys carry no infrastructure entity
yet.
