Project-level webhook subscriptions for run lifecycle events.
Overview
Webhook subscriptions allow projects to register URLs that receive notifications for run lifecycle events. Unlike per-job webhook_url configuration, subscriptions apply project-wide and support filtering by event type. This provides a centralized way to integrate Strait with external monitoring, logging, or automation systems.
How It Works
Subscriptions are registered per project via the API. When a matching event occurs (e.g., run completed, run failed), the system dispatches a signed HTTP POST to each active subscription URL.
Deliveries use the durable delivery model, meaning they are persisted to the database before dispatch. This ensures that notifications are not lost if a worker process restarts. The system supports automatic retries with exponential backoff and dead letter storage for permanently failing deliveries.
Event Types
| Event Type | Description |
|---|---|
run.completed | Triggered when a job run finishes successfully. |
run.failed | Triggered when a job run fails with an error. |
run.timed_out | Triggered when a job run exceeds its timeout limit. |
run.canceled | Triggered when a job run is manually canceled. |
workflow.completed | Triggered when a workflow DAG finishes successfully. |
workflow.failed | Triggered when a workflow DAG fails. |
Configuration
Webhook subscriptions are always available for project-level webhook delivery.
The circuit breaker protects subscription endpoints from cascading failures. If a target URL consistently returns errors, the circuit breaker will temporarily disable delivery to that endpoint to prevent system resource exhaustion.
Security
All deliveries are signed with HMAC-SHA256 using the subscription's secret. This ensures the authenticity and integrity of the notification, allowing your service to verify that the request originated from Strait.
The signature is included in the X-Strait-Signature header. Receivers should also validate the X-Strait-Timestamp to protect against replay attacks. See the webhooks concept doc for detailed signature verification steps and implementation examples.