Webhooks allow workflows to interact with external systems by listening for and responding to events.

Overview

A workflow has only one webhook by design. Each webhook exposes a unique URL endpoint to receive events from other systems and forward them entrypoints in Tracecat Workflows.

The webhook format is:

$TRACECAT__PUBLIC_RUNNER_URL/$WORKFLOW_ID/$WEBHOOK_SECRET

You can get this URL from the Trigger block in the UI, or by making a GET request to the API. Using the CLI this would be:

tracecat workflow inspect $WORKFLOW_ID

Filters

A webhook can be configured with filters. A filter performs checks on incoming data or other factors to decide if a workflow should run.

Some benefits of using filters include the ability to:

  • Ignore certain events from triggering a workflow
  • Prevent a workflow from being executed if certain conditions are not met
  • Apply rate limiting to prevent abuse or overloading the system (coming soon)
  • Reject events that do not conform to some HTTP headers or other network security requirements (coming soon)
  • Perform callbacks without scheduling a workflow (coming soon)

A filter is a set of conditions that must be satisfied before a workflow is executed. Each condition is a full expression that returns a boolean.

example_filter.yaml
triggers:
  - type: webhook
    ref: my_webhook_with_filters
    filters:
      - kind: all # all conditions must be satisfied
        conditions:
          - ${{ FN.not_null(TRIGGER.value) }}
          - ${{ FN.equals(TRIGGER.value, "123456") }}
      - kind: any # any condition must be satisfied
        conditions:
          - ${{ FN.not_null(TRIGGER.value) }}
          - ${{ FN.contains([1, 2, 3], TRIGGER.value) }}

Filters are always evaluated in the order they are defined, and likewise for the conditions within each filter. If no filters are configured, a webhook will simply always schedule a workflow for execution.

This feature is not yet implemented.

Authentication

Our current webhook implementation uses a secret attached to the path to verify the authenticity of incoming requests.

We are migrating our webhook infrastructure to use Svix for secure and resilient webhook delivery.