Skip to main content
Version: v1

Webhook deployment

In a webhook deployment, the deployment script triggers a remote deployment by calling an HTTP endpoint. Use it with an external system or a custom deployment pipeline that exposes a webhook URL.

This page is for the lead or DevOps engineer whose hosting platform or deployment pipeline starts a deployment from a webhook. It covers the request the deployment script sends, the variables that shape it and the setup steps.

note

This deployment type triggers the deployment itself. To call a webhook about a deployment, for example to tell a monitoring system that a deployment happened, use the webhook notification channel.

How it works​

When $VORTEX_DEPLOY_TYPES includes webhook, the deployment script calls the configured webhook URL with curl, using the configured HTTP method and following redirects. The request carries no deployment data, so put anything the receiving end needs in the URL itself.

The deployment passes when the status of the final response, after any redirects, matches VORTEX_DEPLOY_WEBHOOK_RESPONSE_STATUS. Any other status, or a request that can't connect, stops the deployment with [FAIL] Unable to complete webhook deployment., which doesn't include the received status.

Configuration​

Configure the deployment with the variables in the following table, then follow the setup steps.

Environment variables​

The Deployment overview explains the Location values and how the script loads .env. The following table lists the variables that the webhook deployment script reads:

VariableRequiredDefaultLocationDescription
VORTEX_DEPLOY_WEBHOOK_URLYesNoneCIThe webhook URL to call
VORTEX_DEPLOY_WEBHOOK_METHODNoGET.envHTTP method, for example GET or POST
VORTEX_DEPLOY_WEBHOOK_RESPONSE_STATUSNo200.envExpected HTTP response status code

Setup​

To set up webhook deployment:

  1. Add webhook to the comma-separated VORTEX_DEPLOY_TYPES list in your .env file, for example VORTEX_DEPLOY_TYPES=artifact,webhook. With webhook as the only type, the line reads:

    .env
    VORTEX_DEPLOY_TYPES=webhook

  2. Set VORTEX_DEPLOY_WEBHOOK_URL in your CI provider's settings:

    • On GitHub Actions, add a repository variable of the same name, which the shipped workflow reads.
    • On CircleCI, add a project environment variable.

  3. Optional: If the URL carries a token, store it as a GitHub Actions secret:

    1. Add the URL as a repository secret named VORTEX_DEPLOY_WEBHOOK_URL.
    2. In .github/workflows/build-test-deploy.yml, change vars to secrets in the VORTEX_DEPLOY_WEBHOOK_URL line of the Deploy step.

Confirm that the next deployment called the webhook. The deploy job log shows Webhook call completed., then [ OK ] Finished webhook deployment. These lines confirm only the call and its response status, so check the receiving system to confirm that it ran the deployment.

Use cases​

Webhook deployment fits these setups:

  • Triggering deployments on platforms that provide webhook endpoints
  • Integrating with custom deployment orchestration systems
  • Starting an external system's own deployment after CI passes

See also​

The following pages cover the rest of the deployment flow: