Skip to content
bucker

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.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.