Webhooks & Event Notifications
Relevant source files
The following files were used as context for generating this wiki page:
The Webhook Service in Daytona provides a mechanism for notifying external systems about internal lifecycle events. It utilizes Svix as the underlying delivery provider to manage webhook endpoints, security, and retry logic. This system ensures that developers can build integrations that respond automatically to changes in sandboxes, snapshots, and volumes.
Sources: apps/api/src/webhook/README.md:1-5
System Architecture
The webhook architecture follows an event-driven pattern within the Daytona API. When a resource (like a sandbox) changes state, an internal event is published. A dedicated handler catches these events and uses the WebhookService to forward them to Svix, which then delivers them to the user-configured endpoints.
Event Propagation Flow
This diagram illustrates how an internal event triggered by a resource change is processed through the system before being dispatched to external consumers via Svix.
Sources: apps/api/src/webhook/README.md:104-114, apps/api/src/webhook/controllers/webhook.controller.ts:110-115
Configuration and Management
The service requires specific environment variables to interface with the Svix provider. Organization-level isolation is maintained by creating distinct Svix "Applications" for each organization within Daytona.
Key Configuration Variables
| Variable | Description | Requirement |
|---|---|---|
SVIX_AUTH_TOKEN | Authentication token for the Svix API. | Required |
SVIX_SERVER_URL | URL for the Svix server (supports self-hosted). | Optional |
Sources: apps/api/src/webhook/README.md:7-14
Initialization Status
The dashboard verifies if webhooks are initialized for the current organization by checking for a valid svixApplicationId. If not initialized, users can trigger the creation of a Svix application through the management interface.
Sources: apps/dashboard/src/hooks/useWebhooks.ts:10-14, apps/api/src/webhook/controllers/webhook.controller.ts:130-143
Webhook Events and Payloads
Daytona supports several event categories. Each event type is defined in the OpenAPI specification to allow for strict schema validation and documentation in the Svix portal.
Supported Event Types
| Category | Event Types | Description |
|---|---|---|
| Sandbox | sandbox.created, sandbox.state.updated | Triggered during sandbox lifecycle changes. |
| Snapshot | snapshot.created, snapshot.state.updated, snapshot.removed | Triggered when snapshots are managed. |
| Volume | volume.created, volume.state.updated | Triggered when persistent volumes are modified. |
Sources: apps/api/src/webhook/README.md:47-60, apps/api/src/openapi-webhooks.ts:40-140
Payload Structure Example: Sandbox State Updated
{
"id": "sandbox-uuid",
"organizationId": "org-uuid",
"oldState": "STOPPED",
"newState": "STARTED",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
Sources: apps/api/src/webhook/README.md:75-81
API Endpoints
The WebhookController exposes endpoints for managing the lifecycle of webhooks, accessing the Svix portal, and monitoring delivery status.
| Method | Endpoint | Description |
|---|---|---|
POST | /webhooks/organizations/:orgId/initialize | Creates a Svix application for the organization. |
POST | /webhooks/organizations/:orgId/app-portal-access | Returns a URL to the Svix Consumer App Portal. |
POST | /webhooks/organizations/:orgId/send | Sends a manual/custom webhook message (Admin only). |
GET | /webhooks/organizations/:orgId/messages/:msgId/attempts | Retrieves delivery attempt logs (Admin only). |
GET | /webhooks/status | Returns whether the global webhook service is enabled. |
Sources: libs/api-client/src/api/webhooks-api.ts:31-150, apps/api/src/webhook/controllers/webhook.controller.ts:40-110
User Interface and Management
The Daytona Dashboard provides a dedicated management page for webhooks. It is organized into two primary views: Endpoints and Messages.
Dashboard Components
- WebhooksEndpointTable: Displays configured targets, allowing users to disable or delete specific endpoints.
- WebhooksMessagesTable: Provides a history of sent messages and their delivery statuses.
- App Portal Integration: For advanced management, Daytona provides access to the Svix Consumer App Portal, which includes detailed delivery debugging and monitoring.
Conclusion
The Webhooks and Event Notifications system provides a robust integration layer for Daytona. By leveraging Svix, it ensures reliable delivery and security for organization-specific events. The architecture supports both automatic resource lifecycle events and manual administrative messages, accessible via the Daytona API and Dashboard.