Legacy per-server automatic deployment webhooks
Before 6 April 2018, automatic deployment webhooks were configured per server rather than per project. DeployHQ has used a single project-wide webhook since then, but the older per-server URLs were deliberately left working, so a project set up before that date -- or one that copied its webhook from a project that was -- may still be using one.
These URLs continue to work, and there is no plan to withdraw them. They do, however, behave differently from the current project-wide webhook, and the difference is not visible anywhere in the DeployHQ interface.
If automatic deployments run for one server but never for another in the same project, this is the most likely cause.
Identifying which webhook you have
Look at the webhook URL configured in your repository host. There are two formats:
Current (project-wide):
https://youraccount.deployhq.com/deploy/your-project/AbCdEf123456...
Legacy (per-server):
https://youraccount.deployhq.com/deploy/your-project/to/development/abc123def456
The legacy format contains /to/ followed by two extra segments. The segment after /to/ is the permalink of one specific server or server group, and the final segment is that server's own key.
Note that this segment often reads like an environment name -- development, staging, production -- because servers and groups are frequently named after the environment they deploy to. It is still one named target, not an environment.
Why one server deploys and another does not
A legacy webhook deploys only the target named in its URL. It cannot deploy anything else in the project, regardless of how those other servers are configured.
If the named target is a server group, the deployment covers every enabled server in that group -- so a legacy group webhook can already deploy several servers at once. What it still cannot do is reach a server outside the group.
If the named target is a single server, only that one server deploys.
Either way, a server that is not the named target, and not a member of the named group, will never deploy automatically from that webhook -- even when:
- Auto deploy is switched on for it
- Its Branch to deploy from matches the branch you pushed
- Its environment matches the other server
- It is otherwise identical to the server that does deploy
The settings are correct. They simply are not consulted, because the webhook never reaches that server.
Note that you can have more than one legacy webhook for the same project -- one per target. Several legacy webhooks can therefore cover several servers independently, but each one still only deploys its own target.
By contrast, the current project-wide webhook evaluates every enabled server in the project on each push, and queues a deployment for each one whose settings match.
Other things that behave differently
Two further differences commonly cause confusion:
Received Hooks entries are not recorded. The Received Hooks section on the Automatic Deployments page only lists deliveries to the project-wide webhook. If you are using a legacy per-server webhook, that section stays empty even though DeployHQ is receiving and acting on your webhooks normally. An empty Received Hooks list is therefore not evidence that your repository host failed to deliver anything.
Commit message deployment commands have no effect on the target. With a legacy webhook, the server to deploy is fixed by the URL itself. A commit message command naming a different server cannot redirect the deployment to it, no matter how the command is written or quoted.
Migrating to the project-wide webhook
- In DeployHQ, open the Automatic Deployments page for your project and copy the webhook URL shown at the top. This is the project-wide URL.
- Before switching, review every server in the project and confirm its Branch to deploy from and auto deploy toggle are set as you want them. The project-wide webhook considers all of them, so a server you had not previously been deploying automatically may begin to do so.
- If your project has a webhook secret set in DeployHQ, check it now -- see the warning below.
- In your repository host, replace the legacy webhook with the project-wide URL. If you have several legacy webhooks for the same project -- one per target -- replace all of them with the single project-wide URL.
- Push a commit to a tracked branch and confirm the expected servers deploy.
If you use a webhook secret
This applies to GitHub and GitLab repositories only, and it is the one thing that can make a migration fail immediately.
Legacy webhooks do not check the webhook secret at all. The project-wide webhook does, whenever a webhook secret is saved against your repository in DeployHQ. The check differs by host:
- GitHub signs the payload, and DeployHQ verifies that signature against your secret
- GitLab sends the secret itself as a token header, which DeployHQ compares to the one you saved
Either way, if a secret is set in DeployHQ but the matching value was never configured on the webhook at your repository host, every delivery to the new URL is rejected and no deployment is queued.
Before you switch, either configure the same secret on the webhook at your repository host, or clear the secret in DeployHQ. The rejection is recorded under Received Hooks with a secret-mismatch message, so if deployments stop the moment you migrate, check there first.
After migrating, deliveries appear under Received Hooks, where you can open any entry to see which servers were evaluated and why each was or was not queued.
Should I migrate?
Migrating is recommended, but not urgent. These webhooks have kept working since 2018 and are not scheduled for removal, so a legacy webhook that deploys its named target is doing exactly what it was built to do.
Migrate if you want any of the following:
- More than one server in the project deploying automatically from a single push
- Received Hooks entries for troubleshooting
- Commit message deployment commands to select which server is deployed
For a full description of the current model, see How to set up automatic deployments.