Webhooks

Deploy on push with GitHub, GitLab or any caller: the URL, how requests are verified, which pushes deploy, and the answers.

When to use this

You want a site to deploy when code is pushed. Sites connected to GitHub through pfcloud's GitHub App need no webhook at all (see Create a site). Use the deploy webhook for GitLab, Bitbucket, CI jobs, or GitHub repositories you did not connect through the app.

The URL

POST https://YOUR-MYFORGE/api/hooks/deploy/WEBHOOK_KEY

WEBHOOK_KEY is a random 40-character key per site, never the site's id. It is shown on the site page with the secret.

Turn it on

Dashboard: site page, Deployments, turn on deploy on push.
API: PATCH /sites/{site} with {"auto_deploy": true}. If this created the webhook, the answer includes deploy_webhook with the URL and the secret, once.
Replace it: POST /sites/{site}/deploy-webhook with {"confirm": "your-domain.example.com"}. The new URL and secret are shown once. The old ones stop working. The answer is not stored for idempotent replays, so save it at once.

Sites with auto_deploy off, and unknown keys, answer 404. The endpoint reveals nothing about them.

How the request is verified

The secret is checked in one of three ways, depending on the caller:

Caller	How to send the secret
GitHub	Set the webhook's Secret. GitHub signs the body and sends `X-Hub-Signature-256: sha256=<hmac>`. Content type `application/json`, event "Just the push event".
GitLab	Put the secret in Secret token. GitLab sends `X-Gitlab-Token`.
Anything else (CI, Bitbucket, curl)	Add `?token=SECRET` to the URL.

A wrong secret answers 403.

curl -X POST "https://YOUR-MYFORGE/api/hooks/deploy/WEBHOOK_KEY?token=SECRET"

Which pushes deploy

For GitHub and GitLab only a push to the site's configured branch deploys. Other events and other branches are answered with a message that starts with "Ignored". A GitHub ping answers pong. For the generic ?token= call, any request deploys the site's branch.

Answers

Status	Meaning
`202`	Deployment queued. The answer has `message` and the deployment `id`.
`200`	Ignored (not a push, or another branch), or `pong`.
`403`	Invalid signature or token.
`404`	Unknown key, or deploy on push is off.
`409`	Not queued: the site cannot be deployed right now, or a deployment is already running.

The deployment follows the normal rules, including the code scan before any build step. Follow it with GET /sites/{site}/deployments.

Safety

Treat the URL and the secret as passwords. Anyone with both can trigger deploys of that branch.
Replace them if they leak.
pfcloud's own GitHub webhook (/api/github/webhook) is separate and is set up by the platform administrator. You do not call it.