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 for directory: $TERRATEAM_DIR"}', '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
• Before or after an apply operation
• On success or failure of a plan or apply step (via workflows)

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

Distinguishing Between Success and Failure

Terrateam’s hooks run after a complete operation but cannot distinguish between success and failure. For conditional behavior, use the workflows section with the run_on attribute:

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:

• 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

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
        cmd: ['curl', '-X', 'POST', '-H', 'Content-type: application/json', '--data', '{"event":"plan_completed", "directory":"$TERRATEAM_DIR", "workspace":"$TERRATEAM_WORKSPACE", "plan_file":"$TERRATEAM_PLAN_FILE"}', 'https://hooks.example.com/terrateam-webhook']