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 prefix | Fires on | Payload |
|---|---|---|
task.* | Task lifecycle events — created, assigned, status changed, decomposed, closed | Operator identity, audit-chain entry identifier |
signal.* | Orchestrator signals — raised, acknowledged, escalated, resolved | Department, severity, delegator identity on acknowledgements |
pearl.* | Pearl lifecycle — trained, retrained, memory registered, insight produced | Scoped to the Pearl’s department |
audit.* | Audit chain — entry written, verification run, receipt issued | Chain entry identifiers, receipt signatures |
identity.* | Identity plane — token issued, Cradle attested, tier escalated, delegation granted | Standard 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 → 24hSubscriptions 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.
Python
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.