Webhooks

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.

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.

​

Authentication

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