Webhooks

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

  1. From the Application overview, select an existing Application you want to add users to.
  2. Select App settings and navigate to the Manage Webhooks section.
  3. Enter the following details and choose Create to create a webhook.
    1. Enter the name of a webhook.
    2. Enter the URL of the webhook.
    3. (optional) Specify headers and payloads.
    4. Select a trigger.

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}'"  
}'

Where the following environment variables are set:

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). 

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"
  }]
}

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:

{
	"application": "${app_id}",
	"environment": "${env_id}",
	"deployment": "${deploy_id}",
	"status": "${status}"
}

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

Integrate