Webhook

The webhook channel sends an HTTP request with a JSON payload to any URL you choose. Use it for a service that has no channel of its own.

This page is for the lead or DevOps engineer who sends deployment events to a service of their own. It covers the setup steps, every variable the channel reads and the payload it sends. To start a deployment with a webhook, see Webhook deployment.

Setup

To set up webhook notifications:

1. Set VORTEX_NOTIFY_WEBHOOK_URL in your .env file or in your hosting provider's environment variables. When the URL carries a secret, such as an API key, use the hosting environment variables.
2. Add webhook to the comma-separated VORTEX_NOTIFY_CHANNELS list in your .env file, for example VORTEX_NOTIFY_CHANNELS=email,webhook.

Confirm that the next deployment called the URL. The deployment output on your hosting platform shows [ OK ] Finished webhook notification. Check that your service received the payload.

Environment variables

See the Notifications overview for the router, what a failed channel stops, the shared VORTEX_NOTIFY_* variables and the Location column. The following table lists the variables that the webhook channel reads:

Variable	Required	Default	Location	Description
VORTEX_NOTIFY_WEBHOOK_URL	Yes	None	.env or Hosting	Webhook endpoint URL
VORTEX_NOTIFY_WEBHOOK_METHOD	No	POST	.env	HTTP method
VORTEX_NOTIFY_WEBHOOK_HEADERS	No	Content-type: application/json	.env or Hosting	Pipe-separated headers
VORTEX_NOTIFY_WEBHOOK_PAYLOAD	No	Default template	.env	JSON payload
VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS	No	200	.env	Expected HTTP status
VORTEX_NOTIFY_WEBHOOK_BRANCHES	No	None	.env	Exact branch names to send for (comma-separated); empty sends for every branch
VORTEX_NOTIFY_WEBHOOK_PROJECT	No	VORTEX_NOTIFY_PROJECT	.env	Project name
VORTEX_NOTIFY_WEBHOOK_LABEL	No	VORTEX_NOTIFY_LABEL	Hosting	Deployment label
VORTEX_NOTIFY_WEBHOOK_ENVIRONMENT_URL	No	VORTEX_NOTIFY_ENVIRONMENT_URL	Hosting	Environment URL
VORTEX_NOTIFY_WEBHOOK_LOGIN_URL	No	VORTEX_NOTIFY_LOGIN_URL	Hosting	Login URL
VORTEX_NOTIFY_WEBHOOK_EVENT	No	VORTEX_NOTIFY_EVENT, then post_deployment	Hosting	Deployment event; pre_deployment sends nothing
VORTEX_NOTIFY_WEBHOOK_LOG	No	VORTEX_NOTIFY_LOG, then 0	.env	1 inserts the collected deployment log at the %deployment_log% token; 0 leaves it out
VORTEX_NOTIFY_WEBHOOK_LOG_FILE	No	VORTEX_NOTIFY_LOG_FILE	Hosting	Log file inserted at the %deployment_log% token; the router sets the default

Separate multiple headers with |, for example Content-type: application/json|Authorization: Bearer API_KEY. A value of your own replaces the default header, so when your service expects JSON, include Content-type: application/json in your value. When a header carries a credential, set the headers in the hosting environment variables. The deployment output prints the full header value, credential included, so restrict who can read the deployment log.

The scripts load .env as a Bash file, so wrap a value that holds spaces, | or JSON in single quotes:

.env

VORTEX_NOTIFY_WEBHOOK_PAYLOAD='{"text": "%message%"}'

Default payload template

When VORTEX_NOTIFY_WEBHOOK_PAYLOAD is empty, the channel sends the following payload:

{
  "channel": "Channel 1",
  "message": "%message%",
  "project": "%project%",
  "label": "%label%",
  "timestamp": "%timestamp%",
  "environment_url": "%environment_url%",
  "login_url": "%login_url%"
}

The %message% token expands to the full deployment message with all other tokens replaced. When the deployment log is on, message ends with the collected log, because the message carries the %deployment_log% token.

A custom payload can use every token from the token table, including %deployment_log%. The channel JSON-escapes each value before it substitutes it, so a quote in a label can't break the payload.

The channel follows redirects and sends nothing on pre_deployment. The request fails when the response status doesn't match VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS or the request can't connect. The deployment output then shows [FAIL] Unable to send notification to webhook followed by the full webhook URL. That line includes any secret the URL carries, even when the URL comes from the hosting environment variables.