Webhook

A Webhook represents an outbound HTTP subscription registered by a workspace. When a watched event fires (e.g. document.processed, document.uploaded), the platform enqueues a Cloud Tasks HTTP POST to target_url carrying the event payload and any caller-supplied custom headers. One workspace may register multiple webhooks; parent-workspace webhooks also fire for child workspaces. Webhooks are soft-deleted and workspace-scoped.

Naming	Value
Object	Webhook
Resource type (JSON:API `type`)	`webhook`
Collection / records root	— _{(not a records root)}
REST base	`/v1/subscriptions/webhooks`
Entity class	`Webhook`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/subscriptions/webhooks`	🟡 Planned
Retrieve	`GET /v1/subscriptions/webhooks/{id}`	🟡 Planned
Create	`POST /v1/subscriptions/webhooks`	🟡 Planned
Update	`PATCH /v1/subscriptions/webhooks/{id}`	🟡 Planned
Delete	`DELETE /v1/subscriptions/webhooks/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
webhook_id	string (UUID) 🔒 system	✅ Yes	UNIQUE; default gen_random_uuid()	—	Public stable identifier for the webhook. Generated at creation; never changes.
target_url	string	✅ Yes	varchar(255); must be a valid URL (Zod .url() at API boundary)	—	The HTTPS endpoint to which the platform delivers event payloads via Cloud Tasks HTTP POST.
event	string (enum)	✅ Yes	varchar(255); allowed values enforced by Zod schema	document.processed \| document.uploaded	The workspace event type that triggers delivery. Only one event type per webhook registration.
headers	object (JSONB) \| null	⚪ No	jsonb; nullable; key-value map of strings	—	Optional custom HTTP headers merged into the delivery request (e.g. Authorization, X-Source). Sent as-is by the platform.
active	boolean 🔒 system	✅ Yes	default true	—	Whether the webhook is currently enabled. Defaults to true on creation. Not exposed in the update schema — cannot be toggled via the API.
created_at	datetime 🔒 system	✅ Yes	timestamptz; set by onCreate hook	—	ISO 8601 timestamp of when the webhook was created.
updated_at	datetime 🔒 system	⚪ No	timestamptz; nullable; set by onCreate and onUpdate hooks	—	ISO 8601 timestamp of the last update. Null until first modification.
deleted_at	datetime 🔒 system	⚪ No	timestamptz; nullable	—	Soft-delete timestamp. When set, the webhook is excluded from all queries and no longer delivers events. Set by the DELETE endpoint.

Relationships

Name	Type	Required	Description
workspace	to-one (ManyToOne)	✅ Yes	The workspace that owns this webhook. All queries filter by workspace_pk. Parent-workspace webhooks also fire for child workspaces during delivery. References Workspace.

System-computed

webhook_id — gen_random_uuid() at insertion; also written by WebhookService.createWebhook via crypto.randomUUID() (redundant but consistent)
created_at — set by onCreate hook (new Date())
updated_at — set by onCreate and onUpdate hooks; null until first update
deleted_at — set to new Date() by WebhookService.deleteWebhook on soft-delete; not a MikroORM hook, explicit assignment
active — defaults to true at ORM level; no toggle exposed via API
Deduplication guard — WebhookService.createWebhook checks for an existing non-deleted webhook with the same (target_url, event, workspace) triple before inserting; raises WEBHOOK_ALREADY_EXISTS on collision
Delivery via Cloud Tasks — sendWebhookRequest dispatches through CloudTasksService.createHttpPostTask with taskId webhook-trigger---; the actual HTTP call is async and not reflected back on the entity
idx_webhooks_workspace_deleted — composite partial index on (workspace_pk, deleted_at) added by Migration20260416000000 for hot-path list queries

Example

{
  "data": {
    "type": "webhook",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "attributes": {
      "event": "document.processed",
      "target_url": "https://api.example.com/well-events",
      "headers": {
        "Authorization": "Bearer secret-token",
        "X-Source": "well"
      },
      "active": true,
      "created_at": "2026-03-15T10:30:00.000Z",
      "updated_at": "2026-04-01T08:00:00.000Z"
    }
  }
}

_{Source: apps/api/src/database/entities/Webhook.ts · domain: platform · tier: Platform}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example