Skip to content
Install

Update an app with a webhook

A webhook token lets a CI pipeline or another external system update an app without an Orchard account. After your pipeline pushes a new image, one POST request with the token rolls the app onto that image. A request without an image restarts the app.

Each token belongs to one app. GitHub webhooks for auto-deploy are separate. The GitHub App handles them.

  1. Open the app.
  2. Go to Activity.
  3. In Webhooks, enter a label, such as github-actions.
  4. Select Create token.
  5. Copy the webhook URL and the token. Orchard shows them only once.

The dashboard shows Webhooks for apps that do not build from a GitHub repository. For a GitHub app, use the CLI.

Store the token in your CI system’s secret store. Anyone with the token can change the app.

Send the token in the Authorization header. The header form keeps the token out of proxy and access logs.

To restart the app:

curl -X POST https://orchard.example.com/apiv1/webhooks/deploy \
-H "Authorization: Bearer $WEBHOOK_TOKEN"

To roll an image app onto a new tag:

curl -X POST https://orchard.example.com/apiv1/webhooks/deploy \
-H "Authorization: Bearer $WEBHOOK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"tag": "v1.2.3"}'

To roll an image app onto a new image and tag, send {"image": "ghcr.io/org/app", "tag": "sha-abc123"}.

The token also works in the URL, as /apiv1/webhooks/deploy/<token>. The URL that the dashboard shows uses this form.

RequestApp typeResult
No image or tagAnyRestarts the app on its current image.
With image or tagImageRolls the app onto the new image. The previous image stays available for rollback.
With image or tagGitHubReturns a 400 error. To rebuild a GitHub app, push to the branch or run orchard deploy rebuild <id>.

A request returns a 409 error while the app is building. Each token allows 30 requests per minute.

Anything still using a deleted token stops working immediately.

  1. Open the app.
  2. Go to Activity > Webhooks.
  3. Select the delete icon on the token.
  4. Select Delete token.

To rotate a token, create a new one, update the caller, then delete the old one.

A token also stops working if the person who created it loses edit access to the project, or if the API token that created it is revoked or expires. Orchard deletes such a token the next time a request uses it.