Skip to Content
IntegrationWebhooks

Webhooks

The webhook surface delivers substrate events to customer endpoints under the same identity, tier, and audit-chain semantics as every other operation. Every outbound delivery and every received response produces an audit-chain entry.

Event topics

Topic prefixFires onPayload
task.*Task lifecycle events — created, assigned, status changed, decomposed, closedOperator identity, audit-chain entry identifier
signal.*Orchestrator signals — raised, acknowledged, escalated, resolvedDepartment, severity, delegator identity on acknowledgements
pearl.*Pearl lifecycle — trained, retrained, memory registered, insight producedScoped to the Pearl’s department
audit.*Audit chain — entry written, verification run, receipt issuedChain entry identifiers, receipt signatures
identity.*Identity plane — token issued, Cradle attested, tier escalated, delegation grantedStandard subscription set for security operations centres

Delivery semantics

Each subscription targets a single URL. Deliveries are at-least-once and idempotent by event_id. Endpoints must accept duplicate deliveries without side effects. The platform retries against any non-2xx response.

Order within a topic-and-target pair is preserved on a best-effort basis. Handlers requiring strict order must sort by the sequence field on the payload rather than rely on delivery order.

Retry envelope

Failed deliveries are retried on an exponential-backoff schedule:

30s → 2m → 10m → 1h → 6h → 24h

Subscriptions with six consecutive failed deliveries are moved to a quarantined state. New events are queued rather than delivered, and the subscription owner receives written notice. Endpoint restoration followed by a call to webhooks/resume replays the queued backlog in order.

Quarantine protects the platform’s outbound queue from a silently unhealthy customer endpoint. It does not impose a delivery-attempt limit. Once a subscription is resumed, every queued event is delivered.

Signature verification

Every delivery carries an X-Nebbos-Signature header containing an HMAC-SHA-256 of the request body, keyed with a subscription-scoped secret. Signature verification is executed in constant time in advance of payload processing.

import hmac, hashlib def verify(body: bytes, header: str, secret: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, header)

Subscription secrets are unique per subscription and rotatable on request.

Audit-chain integration

Outbound deliveries (event, target URL, timestamp) and receiver responses (status code, duration) are recorded in the audit chain. Quarantine events, resumed backlogs, and signature-verification failures are legible from a single chain read.