Webhooks & Event Triggers

Relevant source files

The following files were used as context for generating this wiki page:

• dev/knowledge/backend/webhooks.md
• specs/archive/ifc-2755-webhook-delivery-operability/plan.md
• specs/archive/infp-445-webhook-headers/spec.md
• dev/guides/backend/creating-async-tasks.md
• specs/archive/ifc-2755-webhook-delivery-operability/ui-test-plan.md
• backend/infrahub/webhook/models.py
• backend/infrahub/trigger/models.py

Infrahub webhooks deliver HTTP notifications to external systems when specific internal events occur. The system integrates Prefect automations to perform event matching and executes a delivery pipeline supporting raw payloads, HMAC-SHA256 signing, and custom Python transformations.

The architecture separates event detection from delivery processing. Built-in triggers monitor the Infrahub graph and configure Prefect automations, which then invoke asynchronous workflows to process and send the webhook data. For details on the underlying task infrastructure, see Async Tasks.

Sources: dev/knowledge/backend/webhooks.md:3-8, dev/knowledge/backend/webhooks.md:215-224

System Architecture

The webhook system operates through a multi-stage pipeline involving GraphQL mutations, built-in triggers, and Prefect workflows.

Architecture Overview Diagram

This diagram illustrates the flow from a graph change to an external HTTP POST request.

Core Components

• Built-in Triggers: Monitor node lifecycle events (created, updated, deleted) to sync webhook configurations with Prefect automations.
• Prefect Automations: Match internal events based on type, branch scope, and node kind.
• Processing Flows: Asynchronous tasks that resolve webhook configurations from the cache or database and prepare the delivery.
• Delivery Flows: Handle the actual HTTP transmission, including header resolution, signing, and retry logic.

Sources: dev/knowledge/backend/webhooks.md:86-98, dev/knowledge/backend/webhooks.md:144-156

Webhook Types and Data Models

Infrahub implements a class hierarchy for webhooks, allowing for different payload behaviors and transformation capabilities.

Webhook Hierarchy

Type	Class	Payload Behavior	Signing
Standard	StandardWebhook	Raw event data + context	Required
Custom	CustomWebhook	Raw event data + context	Optional
Transform	TransformWebhook	Runs a CoreTransformPython from Git	Optional

Sources: dev/knowledge/backend/webhooks.md:55-63

Data Models

• WebhookTriggerDefinition: Bridges Infrahub webhooks to Prefect. It generates unique names formatted as webhook:<id> and defines match criteria for events.
• EventContext: Normalizes raw Prefect event payloads into a structure containing id, branch, account_id, and event_type.
• WebhookHeader: Represents custom HTTP headers. It supports two kinds: static (literal values) and environment (resolved from os.environ at send time).

Sources: dev/knowledge/backend/webhooks.md:86-118

Webhook Class Diagram

The relationships between the base Webhook class and its specialized implementations.

Lifecycle and Processing

1. Trigger Configuration

When a CoreWebhook node is modified, TRIGGER_WEBHOOK_CONFIGURE initiates the configure_webhook flow. This flow performs one of three actions:

• CONFIGURE: Fetches the node, builds a WebhookTriggerDefinition, and updates the Prefect automation.
• DELETE: Removes the corresponding Prefect automation.
• RECONCILE_ALL: Performs a full sync of all active webhooks.

Sources: dev/knowledge/backend/webhooks.md:158-185

2. Event Matching and Delivery

Prefect automations trigger the webhook_process flow when an event matches the configured criteria.

1. Cache Lookup: The system checks Redis for the webhook configuration (webhook:<id>) with a 2-hour TTL.
2. Payload Computation: For TransformWebhook, the system checks out a Git repository and executes Python code to generate the payload.
3. Transmission: The webhook_send subflow executes. It performs 3 retries (4 total attempts) with a fixed 120s delay.

Sources: dev/knowledge/backend/webhooks.md:195-212, dev/knowledge/backend/webhooks.md:237-238

Failure Handling and Operability

The system classifies failures to provide clean, actionable error messages instead of raw stack traces.

Failure Classification

Class	Cause	Transient
CONFIG	Missing environment variable or resolution error	No
CONNECTION	Target endpoint unreachable	Yes
TLS	Certificate validation failure	No
TIMEOUT	Target did not respond within timeout	Yes
HTTP_SERVER_ERROR	Target returned 5xx status	Yes

Sources: dev/knowledge/backend/webhooks.md:215-230

Delivery Operability Layer

Webhook deliveries are first-class objects in the Tasks tab. The operability layer adds:

• HTTP Capture: Redacted request and response artifacts are stored on the Prefect run.
• Traceback Suppression: WebhookDeliveryError is registered to hide stack traces in run logs, surfacing only the classified reason.
• Recovery Actions: Users can RETRY (submits a new run with frozen parameters) or CANCEL (stops remaining retries) through the GraphQL API or UI.

Sources: specs/archive/ifc-2755-webhook-delivery-operability/plan.md:10-18, dev/knowledge/backend/webhooks.md:246-262

Operability Sequence Diagram

This shows how an operator interacts with a failed delivery.

Security and Redaction

HMAC-SHA256 Signing

If a shared_key is configured, Infrahub signs the payload using the following headers:

• webhook-id: Unique message ID (msg_<uuid>).
• webhook-timestamp: Unix timestamp.
• webhook-signature: v1,<base64_signature>.

Sources: dev/knowledge/backend/webhooks.md:286-304

Log Redaction

The system masks sensitive information in logs and captured artifacts. Redaction applies to:

• Environment-sourced header values.
• HMAC signature headers.
• Well-known credential headers (e.g., Authorization, X-API-Key, Cookie).

Sources: dev/knowledge/backend/webhooks.md:306-318, specs/archive/ifc-2755-webhook-delivery-operability/ui-test-plan.md:95-98

Summary

Webhooks & Event Triggers provide a robust mechanism for Infrahub to integrate with external automation stacks. By utilizing Prefect for orchestration, the system ensures delivery reliability through automated retries and detailed operability tools like HTTP capture and failure classification. Security is maintained through flexible HMAC signing and aggressive redaction of sensitive credentials in logs and task artifacts.