Webhooks

Een webhook is een adres dat een extern systeem kan aanroepen om één handeling te starten. HDDeploy kent er drie. Elke webhook heeft een eigen token dat precies één handeling op één stack of site toestaat; het is dus veiliger in een CI-pipeline dan uw persoonlijke API-token.

Deploy-webhook (CI start een deploy)

Op het tabblad Webhooks van een stack:

1. Klik op Enable webhook. Het token wordt één keer getoond; zet het direct in de secret store van uw CI (bijvoorbeeld een GitHub Actions repository secret HDDEPLOY_DEPLOY_TOKEN). Op de server staat alleen een hash.
2. De laatste stap van uw pipeline wordt:

curl -f --retry 5 --retry-delay 30 --retry-all-errors \
     -X POST https://<uw-server>.hddeploy3000.nl/api/stacks/mijnapp/deploy \
     -H "Authorization: Bearer <token>"

• De aanroep wacht op de deploy en mislukt als de deploy mislukt, zodat uw pipeline rood wordt. Met ?async=1 krijgt u direct een 202 en kunt u de taak volgen via GET /api/stacks/mijnapp/jobs/<id> met hetzelfde token.
• Per stack wordt één deploy per 30 seconden geaccepteerd; de --retry in het voorbeeld vangt dat op. Een aanroep tijdens een wachtende deploy sluit daarbij aan.
• Elke aanroep staat op Activity (door “webhook”, met het adres van de aanroeper) en in de lijst Recent webhook deploys op het tabblad.
• Token kwijt: Regenerate (het oude werkt meteen niet meer). Pipeline opgeheven: Revoke.

GitHub push-webhook (bij stacks uit git)

Een stack die uit een git-repository bouwt, controleert de repository elke paar minuten. Met de push-webhook rolt een push binnen seconden uit:

1. Op het tabblad Webhooks, kaart GitHub push webhook: klik op Enable en kopieer de Payload URL (https://<uw-server>.hddeploy3000.nl/api/stacks/mijnapp/github) en het secret.
2. In GitHub: repository Settings > Webhooks > Add webhook. Payload URL en secret invullen, content type application/json, alleen het event “push”.

Alleen pushes naar de ingestelde branch rollen uit; andere branches en de ping van GitHub worden bevestigd en genegeerd, net als pushes terwijl de stack is vastgezet op een commit. Elke geaccepteerde push is een taak (door “github”). Met New secret vervangt u het secret; pas dan ook de webhook in GitHub aan.

Zie ook Bouwen vanuit een git-repository.

Check-webhook (CI laat een site direct synchroniseren)

Uploadt uw pipeline een site naar de FTP-locatie, dan kan hij daarna de server vragen meteen te synchroniseren. Op de pagina van de site, tabblad Webhook: Enable, token kopiëren, en als laatste stap van de uploadtaak:

curl -f --retry 5 --retry-delay 30 --retry-all-errors \
     -X POST https://<uw-server>.hddeploy3000.nl/api/sites/mijnsite/check \
     -H "Authorization: Bearer <token>"

Pas na de upload

Een check via de webhook zet een gevonden wijziging meteen live, zonder de stabiliteitsperiode af te wachten: de aanroeper verklaart dat de upload klaar is. Roep hem dus alleen aan nadat de upload volledig is afgerond, nooit parallel.

De aanroep antwoordt met 202; het resultaat ziet u met GET /api/sites/mijnsite/status (hetzelfde token): lastDeploy schuift op bij succes, lastError noemt een fout. Eén check per site per 30 seconden.

Verschil met de REST API

De REST API op /api/v1 werkt met uw persoonlijke token en kan alles wat u kunt. De webhooks staan daarbuiten, met een eigen token per handeling, en zijn bedoeld voor systemen die u niet uw volledige rechten wilt geven.