Skip to main content

Security, observability, and versioning

Security controls​

  • Derive scope from trusted External Consumer, Workspace, Connection, subscription, or Workflow context; reject payload-selected scope.
  • Validate the destination scheme allowed by the owning surface, DNS/IP results, redirects, response size, timeout, and media/payload bounds to reduce SSRF and rebinding risk.
  • Verify signatures/replay before parsing or business dispatch; rotate secrets and support an overlap policy without logging either secret.
  • Minimize and redact personal fields, provider bodies, tokens, signing material, screenshot bytes, and internal IDs.
  • Keep Event Hook, Provider Webhook, Workflow, and Lead Delivery credentials in their own ownership boundaries.

Safe observability​

Every attempt should expose permissioned metadata such as event/delivery ID, subscription or Workflow action, normalized status, attempt number, correlation ID, timing, response class, retry decision, and terminal/disablement reason. It should not expose raw request bodies, Authorization headers, signing secrets, provider tokens, or unrestricted destination diagnostics.

Endpoint health is an operational signal, not a customer-data export. Monitor latency, response classes, timeout rate, retry volume, terminal failure, disablement, queue age, and dead-letter count with redacted dimensions.

Version compatibility​

Every envelope identifies its contract version and event type. Within a compatible major version, additive optional fields may be introduced; consumers must ignore unknown informational fields only when the contract permits it. Unknown commands, security-sensitive fields, invalid enum values, and unsupported major versions fail explicitly.

{
  "contractVersion": "1.0",
  "eventType": "conversation.started",
  "eventId": "<YOUR_EVENT_ID>",
  "deliveryId": "<YOUR_DELIVERY_ID>",
  "correlationId": "<YOUR_CORRELATION_ID>",
  "data": { "reference": "<YOUR_RESOURCE_REFERENCE>" }
}

For a breaking contract change, publish a new major version and update signing/verification and replay rules together. Do not infer compatibility from a provider’s raw version string.