Webhook events and payloads
Bergur DavidsenUpdated 2026-07-14
Webhook receivers should parse events by type, validate the envelope and resource data, and tolerate compatible additions. Do not deserialize arbitrary payloads directly into trusted commands.
Released public manual testing covers fragment.created, fragment.updated, and fragment.deleted.
Public envelope
Released examples use an envelope shaped like:
{
"type": "fragment.updated",
"workspaceId": "<workspace-id>",
"fragmentId": "<fragment-id>",
"data": {
"id": "<fragment-id>",
"workspaceId": "<workspace-id>",
"fragmentTypeId": "<fragment-type-id>",
"title": "Example fragment",
"summary": "Example summary",
"content": "# Example\n\nFragment content.",
"tags": ["example"],
"status": "active",
"createdVia": "api"
},
"occurredAt": "2026-07-14T12:01:00.000Z"
}This is a workflow example, not a promise that every event includes every field. Validate against the target environment.
Fragment created
Use fragment.created for downstream indexing, synchronization, review queues, or notifications. Do not assume enrichment or search indexing is complete at delivery time; refetch through an authorized API when final state matters.
Symlink automation can produce createdVia: "symlink" with optional symlinkParentId. Consumers that count original authored records should separate these from web, mcp, or api creation.
Fragment updated
Use fragment.updated to refresh derived state. Receivers should upsert by stable fragment ID, compare time/version where available, avoid assuming which field changed, and make repeated updates idempotent.
Events can arrive out of order. Do not overwrite newer state solely because an older delivery arrives later.
Fragment deleted
Use fragment.deleted to remove or tombstone downstream representations. The source might no longer be readable, so retain enough event identity for cleanup without refetching.
Do not cascade destructive deletion into unrelated systems without an explicit reviewed policy.
Validate the envelope
Check recognized type, valid IDs, envelope/data consistency, timestamp, resource shape, payload size, receiver authentication, and approved workspace scope.
Reject or quarantine malformed payloads. Log redacted diagnostics, not full private content.
Test-event header
Manual deliveries include:
x-usable-test-trigger: trueUse it to route tests away from production side effects. It is an indicator, not authentication; receiver authorization must use the configured security mechanism.
Schema evolution
- Ignore unknown additive fields unless policy requires review.
- Reject unknown event types safely.
- Version downstream representations.
- Preserve raw payloads only when retention and privacy permit.
- Fetch the deployed public contract when behavior differs.
Do not publish internal Pathway contracts as the external webhook contract. Public webhooks can expose a smaller or transformed payload.
Sensitive data
Events can include fragment content, metadata, user identifiers, and workspace context. Apply workspace classification and retention rules to receivers, queues, logs, backups, and downstream services.