Webhooks

Webhooks let you trigger Holden deployments from external systems. Instead of waiting for the poll timer (up to 5 minutes), call the webhook after your image is built and pushed.

GitHub Actions Build images and trigger deploys with official Holden actions

Webhook Endpoint

Holden exposes a webhook endpoint on port 6020:

POST /webhook/:app-id

Queues that app for reconciliation. The :app-id must match an app registered in apps.yml. Unknown app-ids are logged and ignored—no error response.

Signature Verification

Holden requires HOLDEN_WEBHOOK_SECRET to be set and verifies all webhook requests using HMAC-SHA256. Webhooks are rejected if the secret is not configured. The actions/deploy action handles signing automatically.

If you’re calling the webhook manually (curl, etc.), include the X-Hub-Signature-256 header with the HMAC-SHA256 signature of the request body.

Lifecycle How webhooks fit into the event-driven queue