Webhooks
On this page
What are Webhooks?
Webhooks are a way to trigger actions in external systems when certain events occur in the Platform Orchestrator. For example, you can employ Webhooks to initiate regression tests automatically whenever a new version of a workload gets deployed.
sequenceDiagram
CI/CD Pipeline ->> Platform Orchestrator: Deploy a new version of the workload
Platform Orchestrator ->> CI/CD Pipeline: Deployment successfullly triggered
Platform Orchestrator ->> Platform Orchestrator: Deploying changes
Platform Orchestrator ->> Testing system: The new version of the workload deployed
Note over Platform Orchestrator,Testing system: Webhook event
Testing system ->> Testing system: Testing workload
Administrator
role within your Organization or the Owner
role on the Application.- From the Application overview, select an existing Application you want to manage webhooks for
- Navigate to the Webhooks section
- Enter the following details and choose Create to create a webhook
- Enter the name of a webhook
- Enter the URL of the webhook
- (optional) Specify headers and payloads
- Select triggers
- Select Create
humctl api POST /orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/webhooks \
-d '{
"headers": {},
"id": "'${ID}'",
"payload": {
"application": "${app_id}",
"environment": "${env_id}",
"deployment": "${deploy_id}",
"status": "${status}"
},
"triggers": [
{
"scope": "'${SCOPE}'",
"type": "'${TYPE}'"
}
],
"url": "'${URL}'"
}'
curl "https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/${HUMANITEC_APP}/webhooks" \
-X POST \
-H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"headers": {},
"id": "'${ID}'",
"payload": {
"application": "${app_id}",
"environment": "${env_id}",
"deployment": "${deploy_id}",
"status": "${status}"
},
"triggers": [
{
"scope": "'${SCOPE}'",
"type": "'${TYPE}'"
}
],
"url": "'${URL}'"
}'
resource "humanitec_webhook" "webhook1" {
id = "my-hook"
app_id = "app-id"
payload = {
"application": "$${app_id}"
"environment": "$${env_id}"
"deployment": "$${deploy_id}"
"status": "$${status}"
}
url = "https://example.com/hook"
triggers = [{
scope = "environment"
type = "created"
}]
}
Where the following environment variables are set (CLI and API only):
Variable | Example | Description |
---|---|---|
HUMANITEC_TOKEN |
lsakdjhcals |
A Humanitec token of a user with at least Manager role on the Organization. |
HUMANITEC_ORG |
my-org |
The Humanitec organization the Application is in. |
HUMANITEC_APP |
app-id |
The ID of the Application. |
ID |
my-hook |
Job ID, unique within the Organization. |
SCOPE |
environment |
Triggering event scope. |
TYPE |
created |
Triggering event type. |
URL |
example.com/hook |
The webhook’s URL (without protocol, only HTTPS is supported). |
Events
Depending on the chosen event, there is a different set of variables available for use in the payload. You can incorporate these variables into your payload as placeholders, as shown below:
{
"app_id": "${app_id}",
"env_id": "${env_id}",
"event": "${event}",
"org_id": "${org_id}",
"triggered_at": "${triggered_at}",
"triggered_by": "${triggered_by}"
}
Environment
Triggered when there are changes in the environment. There are two types of environment events:
- created
- deleted
When defining your payload, you can use the following variables:
Variable | Description | Example |
---|---|---|
${event} |
Name and type of the incoming event | environment.created |
${triggered_at} |
Date and time when the webhook was triggered | 2024-03-22T08:49:23.436635385Z |
${triggered_by} |
User ID of the entity triggering the event | 4b2ad72b-4d79-4124-af07-9dd97d6e9154 |
${org_id} |
ID of the organization | example-org |
${app_id} |
ID of the application | example-app |
${env_id} |
ID of the environment | example-env |
${name} |
Name of the environment | Example env |
${type} |
Type of the environment | development |
Deployment
Triggered when there are changes in the deployment process. There are two types of deployment events:
- started
- finished
When defining your payload, you can use the following variables:
Variable | Description | Example |
---|---|---|
${event} |
Name and type of the incoming event | deployment.finished |
${triggered_at} |
Date and time when the webhook was triggered | 2024-03-22T08:49:23.436635385Z |
${triggered_by} |
User ID of the entity triggering the event | 4b2ad72b-4d79-4124-af07-9dd97d6e9154 |
${org_id} |
ID of the organization | example-org |
${app_id} |
ID of the application | example-app |
${env_id} |
ID of the environment | example-env |
${deploy_id} |
ID of the deployment | 17bf0ac889ee7eae |
${delta_id} |
ID of the delta | 900a4814c4557947b98629f6efad158d122837fe |
${set_id} |
ID of the deployment set | huLPWmcZeokhXIFnbRdmkqxLlGL-WWwBxdPStkidjgk |
${comment} |
Comment of the deployment | Example deployment message |
${status} |
Status of the deployment | succeeded |