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 manage webhooks for
  2. Navigate to the 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 triggers
    5. 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

Container logs