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). 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.0at that commit with the CLI, the platform reports land on1.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.