Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. Extract the timestamp and signature from headers
  2. Reconstruct the signed payload: {timestamp}.{body}
  3. Compute HMAC-SHA256 using the shared secret
  4. Compare the computed signature with the received one (constant-time comparison)
  5. 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:
AttemptDelayCumulative
1st retry1 minute1 minute
2nd retry5 minutes6 minutes
3rd retry30 minutes36 minutes
4th retry2 hours~2.5 hours
5th retry12 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:
CategoryEventsDescription
Schedulesschedule.triggered, schedule.failedSchedule execution events
Agentsagent.registered, agent.health_changedAgent lifecycle events
Assetsasset.created, asset.updated, asset.deletedAsset lifecycle events (files, artifacts, data connections)
Governanceorganization.created, organization.deleted, project.createdTenant-boundary events
Data Connectionsconnection.status_changed, connection.verifiedConnection state changes
Deploymentsdeployment.started, deployment.completed, deployment.failedDeployment 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"
  }
}
FieldDescription
idUnique event ID for idempotency
typeEvent type identifier
timestampISO 8601 UTC timestamp of the event
organization_idOrganization that owns the resource
project_idProject scope (if applicable)
dataEvent-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.