Webhooks
A webhook is a POST request sent to a URL. Use webhooks to trigger an action in response to an event such as a repository push.
This functionality is only available in Portainer Business Edition.
Webhooks are only available on non-Edge environments (environments running Portainer Server or Portainer Agent, not the Portainer Edge Agent). This is because the tunnel to the Portainer Edge Agent is only opened on-demand, and therefore would mean there is no way to expose a webhook permanently.
Enabling an application webhook
From the menu select Applications then select the application that you want to configure the webhook for. Then select the Edit this application button.
Webhooks are only available for applications deployed from a Git repository.
Enable GitOps updates if it is not already enabled and select Webhook
as the Mechanism. When the URL appears, click Copy link. This is the URL used to trigger the webhook.
This example shows how to trigger the webhook:
Using environment variables with webhooks
When triggering a webhook, environment variables can be passed through the endpoint and referenced within the deployment.
Environment variables can not be updated for Pods, only for Deployments.
To specify an environment variable on a webhook, add it as a variable to the URL. For example, to pass a SERVICE_TAG
variable with the value development
:
To reference the SERVICE_TAG
variable in your manifest with a fallback to the value stable
:
Environment variables must already be defined in the manifest - new environment variables cannot be added via the webhook.
Rolling restarts
When using an application's webhook to redeploy your application, you can tell Portainer to perform a rolling restart of the application rather than a "terminate and restart" redeploy.
This functionality is only available in Portainer Business Edition.
To specify this, use the rollout-restart
parameter in your webhook call:
Valid options are as below:
Option | Overview |
---|---|
| All of the application's deployments will be redeployed as a rolling restart. |
| Only the specified deployment(s) will be redeployed as a rolling restart. All other deployments will not be redeployed or restarted. Separate multiple deployments with commas.
This option supports Deployments ( |
If the rollout-restart
parameter is not defined, the webhook will redeploy the application in traditional "terminate and restart" behavior.
If your cluster has a change window enabled, the rolling restart will only be performed within the change window.