Skip to main content
Version: v2

Webhook deployment

Webhook deployment triggers a remote deployment by calling an HTTP endpoint. Use it with external systems or custom deployment pipelines that expose 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 is a deployment type: it triggers the deployment itself. To call a webhook about a deployment (for example, to tell a monitoring system one happened), use the webhook notification channel instead.

How it works​

When webhook is included in $VORTEX_DEPLOY_TYPES, the deployment script calls the configured webhook URL with the configured HTTP method, follows redirects, and waits up to 10 seconds for an answer. It sends no deployment data, so anything the receiving end needs has to be in the URL itself.

The deployment passes when the status of the final response, after any redirects, matches VORTEX_DEPLOY_WEBHOOK_RESPONSE_STATUS. A different status below 400 stops it with [FAIL] Webhook returned unexpected status code, the status it got, and the status it expected. A status of 400 or higher, or a request that can't connect, stops it with [FAIL] Unable to call the deployment webhook.

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, below 400

Setup​

To set up webhook deployment, complete these steps:

  1. Add webhook to the comma-separated VORTEX_DEPLOY_TYPES list in your .env file, for example VORTEX_DEPLOY_TYPES=artifact,webhook. On its own, it looks like this:

    .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, keep it in a GitHub Actions secret instead of a variable:

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

Confirm that the next deployment called the webhook. The deploy job log shows [ OK ] Webhook call completed., followed by [ OK ] Finished webhook deployment. These lines confirm the call and its response status only, 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
  • Telling an external system that CI passed, so it starts its own deployment

See also​

The following pages cover the rest of the deployment flow: