Webhooks

Webhooks enable event-driven communication between CRAFT and external systems. When a platform event occurs (such as a schedule trigger, agent completion, or data connection status change), the webhook system delivers a signed HTTP POST request to a configured endpoint.

Coming Soon, The webhook system described on this page is planned but not yet implemented. This page documents the target architecture and capabilities for an upcoming release. Do not build integrations against these APIs until this warning is removed.

Architecture

The webhook system follows a publish-subscribe pattern built on Redis Streams, consistent with the platform’s infrastructure-agnostic design:

Redis Streams is used instead of cloud-specific message brokers (SQS, Pub/Sub) to avoid cloud-specific dependencies. Redis is already part of the infrastructure stack, so no additional dependencies are required.

Security

HMAC Payload Signing

Every webhook delivery includes an HMAC-SHA256 signature in the request headers, allowing receivers to verify that the payload was sent by the platform and has not been tampered with:

POST /webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Signature: sha256=a1b2c3d4e5f6...
X-Webhook-Timestamp: 1743696000
X-Webhook-Event: schedule.triggered

{...payload...}

Receivers should:

Extract the timestamp and signature from headers
Reconstruct the signed payload: {timestamp}.{body}
Compute HMAC-SHA256 using the shared secret
Compare the computed signature with the received one (constant-time comparison)
Reject payloads older than a configurable tolerance window (e.g., 5 minutes) to prevent replay attacks

SSRF Protection

The webhook dispatcher includes protection against Server-Side Request Forgery (SSRF):

Private/internal IP ranges are blocked by default (10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x)
DNS resolution is validated before delivery
Redirect following is disabled or limited to prevent redirect-based SSRF

Retry Logic

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay	Cumulative
1st retry	1 minute	1 minute
2nd retry	5 minutes	6 minutes
3rd retry	30 minutes	36 minutes
4th retry	2 hours	~2.5 hours
5th retry	12 hours	~14.5 hours

A delivery is considered successful when the receiver responds with a 2xx status code. After all retries are exhausted, the delivery is marked as failed and recorded in the delivery log.

Event Types

The platform plans to support webhook notifications for the following event categories:

Category	Events	Description
Schedules	`schedule.triggered`, `schedule.failed`	Schedule execution events
Agents	`agent.registered`, `agent.health_changed`	Agent lifecycle events
Assets	`asset.created`, `asset.updated`, `asset.deleted`	Asset lifecycle events (files, artifacts, data connections)
Governance	`organization.created`, `organization.deleted`, `project.created`	Tenant-boundary events
Data Connections	`connection.status_changed`, `connection.verified`	Connection state changes
Deployments	`deployment.started`, `deployment.completed`, `deployment.failed`	Deployment lifecycle

Webhook Payload Structure

Webhook payloads follow a consistent envelope format:

{
  "id": "evt-a1b2c3d4",
  "type": "schedule.triggered",
  "timestamp": "2026-04-03T06:00:00Z",
  "organization_id": "acme-corp",
  "project_id": "analytics-prod",
  "data": {
    "schedule_id": "sch-x1y2z3",
    "schedule_name": "Daily Analytics Refresh",
    "run_id": "run-m1n2o3"
  }
}

Field	Description
`id`	Unique event ID for idempotency
`type`	Event type identifier
`timestamp`	ISO 8601 UTC timestamp of the event
`organization_id`	Organization that owns the resource
`project_id`	Project scope (if applicable)
`data`	Event-specific payload

Use the event id field for idempotency. If you receive the same event ID multiple times (due to retries), process it only once.

Multi-Tenancy

Webhooks are scoped to organizations and optionally to projects, following the same isolation model as all platform resources:

Webhook configurations are owned by an organization and optionally scoped to a project
Events are only delivered for resources within the webhook’s scope
Webhook secrets (for HMAC signing) are stored via the Governance Secrets API

Next Steps

Schedules

Configure time-based triggers that generate webhook events.

Agent Registry

Monitor agent lifecycle events via webhooks.

Data Connections

Receive notifications when connection status changes.

Authentication

Understand how webhook endpoints authenticate with the platform.

Overview

Identity & Access

Agents & Services

Memory

Data & Gateways

Webhooks (Planned)

Webhooks

Architecture

Security

HMAC Payload Signing

SSRF Protection

Retry Logic

Event Types

Webhook Payload Structure

Multi-Tenancy

Next Steps

Schedules

Agent Registry

Data Connections

Authentication

​Webhooks

​Architecture

​Security

​HMAC Payload Signing

​SSRF Protection

​Retry Logic

​Event Types

​Webhook Payload Structure

​Multi-Tenancy

​Next Steps

Schedules

Agent Registry

Data Connections

Authentication

Webhooks

Architecture

Security

HMAC Payload Signing

SSRF Protection

Retry Logic

Event Types

Webhook Payload Structure

Multi-Tenancy

Next Steps