Webhooks

Webhooks allow you to integrate Terrateam with external systems by sending HTTP requests to a specified URL when certain events occur during the Terrateam workflow. While Terrateam does not have a dedicated webhooks feature, you can achieve similar functionality by leveraging hooks and workflows in combination with Terrateam’s built-in environment variables.

Configuring Webhooks

To configure webhooks in Terrateam, you can use the hooks or workflows sections in your .terrateam/config.yml file. Here’s an example configuration that sends a webhook request after an apply operation:

hooks:
  apply:
    post:
      - type: run
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply completed"}', 'https://example.com/webhook']

In this example, the hooks.apply.post section defines a run step that uses the curl command to send an HTTP POST request to the specified URL with a JSON payload containing a message.

Webhook Events

You can configure webhooks to be triggered at various points in the Terrateam workflow, such as:

• Before or after a plan operation (hooks, once per operation)
• Before or after an apply operation (hooks, once per operation)
• Before or after the plan or apply of each directory and workspace (workflows)

To trigger webhooks at different events, use the appropriate hooks or define custom steps in workflows.

Distinguishing Between Success and Failure

Both hooks and workflows run steps accept the run_on attribute (success, failure, or always; default success). In a post hook, run_on reflects the result of the whole operation; in a workflow step, it reflects the result of the steps before it for that directory and workspace:

hooks:
  apply:
    post:
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply succeeded"}', 'https://example.com/webhook']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply failed"}', 'https://example.com/webhook']

workflows:
  - tag_query: ""
    apply:
      - type: init
      - type: apply
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply succeeded for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply failed for directory: $TERRATEAM_DIR"}', 'https://example.com/webhook']

Using Environment Variables in Webhooks

Terrateam provides built-in environment variables for context-aware payloads. Which variables are set depends on where the run step executes:

• In workflows steps (per directory and workspace):
  • TERRATEAM_DIR: Directory being processed
  • TERRATEAM_WORKSPACE: Workspace in use
  • TERRATEAM_PLAN_FILE: Path to the plan file
  • TERRATEAM_ROOT: Root path of the repository
• In hooks (once per operation):
  • TERRATEAM_ROOT: Root path of the repository
  • TERRATEAM_RESULTS_FILE (post hooks only): Path to a JSON file with the results of every directory and workspace

A run step whose cmd references an environment variable that is not set fails with a missing environment variable error, so do not use the per-directory variables in hooks.

Securing Webhooks

Best practices:

• Use HTTPS for all webhook URLs
• Include a secret token for authentication
• Sanitize inputs on the receiving end
• Use GitHub Secrets to store tokens

hooks:
  apply:
    post:
      - type: run
        cmd: ['curl', '-X', 'POST', '-d', '{"text":"Apply complete", "token":"$WEBHOOK_SECRET_TOKEN"}', 'https://example.com/webhook']

Examples

Slack Notifications via Workflows

workflows:
  - tag_query: ""
    apply:
      - type: init
      - type: apply
      - type: run
        run_on: success
        cmd: ['curl', '-X', 'POST', '-H', 'Content-Type: application/json', '--data', '{"text":"Apply succeeded for $TERRATEAM_DIR"}', '$SLACK_WEBHOOK_URL']
      - type: run
        run_on: failure
        cmd: ['curl', '-X', 'POST', '-H', 'Content-Type: application/json', '--data', '{"text":"Apply failed for $TERRATEAM_DIR"}', '$SLACK_WEBHOOK_URL']

Custom Webhook Server

hooks:
  plan:
    post:
      - type: run
        run_on: always
        cmd: ['curl', '-X', 'POST', '-H', 'Content-type: application/json', '--data-binary', '@$TERRATEAM_RESULTS_FILE', 'https://hooks.example.com/terrateam-webhook']