Operate / Backend operators

Operate webhooks

Receive notifications as delivery mechanics, deduplicate them, and re-verify the referenced proof or receipt before admission.

verified append notificationsigned webhook delivery and idempotent consumerComplete production checklist

Implementation rail · signed webhook delivery and idempotent consumer

Exact execution and operator checks

01
Operator check
Register the endpoint
Create the endpoint through the authenticated production webhook API, retain the one-time secret in authorized custody, and bind endpoint ID, event allowlist, rotation owner, and deduplication store.
Substantive records: /reference/webhooks · /reference/http-openapi
Expected: Endpoint custody and accepted event scope are explicit.
02
Exact mechanic
Prepare a signed test event
```
curl --fail-with-body --request POST   "https://receiz.com/api/developers/webhooks/${RECEIZ_WEBHOOK_ENDPOINT_ID:?RECEIZ_WEBHOOK_ENDPOINT_ID is required}/test-event"   --header "authorization: Bearer ${RECEIZ_ACCESS_TOKEN:?RECEIZ_ACCESS_TOKEN is required}"   --header "content-type: application/json"   --data '{"eventType":"creator.run.completed"}'
```
Mechanic
POST /api/developers/webhooks/{endpointId}/test-event
Authentication and account boundary
Business session or scoped bearer access token
Exact source
receiz-docs/generated/openapi-reference.json · SHA-256 2278eb9ab1dfcc90d61d4a6f9daac1bc55e17aeeab0d2d5d39228f88654bc20a
Expected: The authenticated endpoint returns a signed test delivery envelope.
03
Operator check
Verify and deduplicate delivery
Verify the exact raw body and signature before parsing; reject stale timestamp, invalid signature, unknown event, and replayed delivery ID; persist deduplication before side effects.
Substantive records: /reference/webhooks · /reference/operations-receipts
Expected: One accepted delivery produces at most one bounded side effect.
04
Exact mechanic
Run test:interoperability-conformance
```
pnpm test:interoperability-conformance
```
Mechanic
pnpm test:interoperability-conformance
Authentication and account boundary
Authorized local repository checkout; the command proves only the checked repository boundary.
Exact source
package.json · SHA-256 132f99232dfaf26f7186b73752938d1377042808f42d60d374fe7b2e57c7646b
Expected: Transport wrappers, digest continuity, and external authority boundaries pass.

Complete operating anatomy

Every boundary required to ship.

Solved outcome: Webhook delivery triggers bounded processing without becoming proof, ownership, settlement, or identity authority.
Prerequisites: Hold the exact webhook endpoint API operation, authenticated Business boundary, endpoint ID, one-time secret custody, raw-body access, signature algorithm, timestamp tolerance, event allowlist, delivery-ID deduplication store, and rotation owner.
Exact primitive: verified append notification
Governing law: Operate webhooks is governed by interoperability-conformance: A passing execution confirms the checked cross-system proof invariants for the exact repository state exercised. reasoning-kernel: Product ontology is decided inside the Receiz authority boundary. canonical-artifact-verifier: The verifier classifies the supplied artifact. Embedded subpayloads and remote responses remain subordinate.
Source-of-truth order: Receiz law → sealed artifact truth → deterministic proof object state → verified durable local or register truth → authenticated snapshot → server distribution, synchronization, indexing, and publication → database, session, observability, and interface projections.
Expected artifact, receipt, or state: A delivery receipt linked to an event identity and the independently fetched or held artifact or state receipt.
Inspection: Inspect the delivery ID, signature check, event type, retry count, referenced operation, and artifact digest. Inspection exposes structure and receipt fields; inspection never establishes verification.
Independent verification: Independent verification for webhooks: verify delivery mechanics, then independently verify the referenced artifact or governed state. This establishes only the verified append notification boundary named by the bound sources; The implementation rail remains beneath proof authority: signed webhook delivery and idempotent consumer.
Offline behavior: Queue exact deliveries during outages and process idempotently later; held artifact truth remains readable.
Identity and account boundary: Public Record Moment, Seal File, Verify, Export, and public proof reading are account-free. Identity is optional and adds continuity, custody, recovery, and governed private controls after proof admission.
Security boundary: Verify the exact raw body and delivery signature, enforce replay bounds, redact secrets, and separate delivery acceptance from proof admission.
Conformance command: pnpm test:interoperability-conformance
Deployment checks: Register the endpoint, store the secret once, verify raw-body signatures before parsing, enforce timestamp and event allowlist, atomically deduplicate delivery IDs before side effects, retry safely, rotate secrets, and retain signed test-event evidence.
Production checklist: Create endpoint; send signed test event; accept valid raw body; reject altered body, wrong signature, stale timestamp, unknown event, and replay; simulate duplicate concurrency and handler failure; rotate secret; verify old secret rejection.
Rollback and containment: Containment for webhooks: The delivery is rejected before parsing or side effects. Obtain the exact raw body and active secret, then process as a new delivery only if valid. Deduplication admits at most one side effect. Inspect the atomic deduplication record and reconcile the original operation. The exposed or prior secret cannot authorize new delivery. Rotate through the exact authenticated endpoint, update custody, and prove old-secret rejection. Preserve every stronger held artifact and admitted state while the named boundary is corrected.

Fail closed

Mutation and failure matrix

Raw-body signature or timestamp verification fails.

Effect: The delivery is rejected before parsing or side effects.
Retry: Never retry acceptance with parsed or reserialized bytes.
Recovery: Obtain the exact raw body and active secret, then process as a new delivery only if valid.

Delivery ID is replayed or races concurrently.

Effect: Deduplication admits at most one side effect.
Retry: Return the documented duplicate handling without repeating mutation.
Recovery: Inspect the atomic deduplication record and reconcile the original operation.

Webhook secret is exposed or rotated.

Effect: The exposed or prior secret cannot authorize new delivery.
Retry: Do not continue accepting both indefinitely.
Recovery: Rotate through the exact authenticated endpoint, update custody, and prove old-secret rejection.

Exact authority

Claim-to-source bindings

A passing execution confirms the checked cross-system proof invariants for the exact repository state exercised.
scripts/test_interoperability_conformance.tsexecutable-conformance · SHA-256 c09d81f36305004f7ee02c40070b3c9cd64d8f5572ce12d211c022f3e75dbf4e
Product ontology is decided inside the Receiz authority boundary.
docs/receiz-reasoning-kernel.mdnormative-doctrine · SHA-256 bbe2eeb58ef1487a84f3e128eaad16215c8aceecf30f3cdc5a68fa6316a844bd
The verifier classifies the supplied artifact. Embedded subpayloads and remote responses remain subordinate.
packages/receiz-sdk/src/artifactVerification.tsimplementation-verifier · SHA-256 c10cdba92568fea273e1d9e7a3321083d52945378ab0cc83aee9720d44f0bba3

One complete system

Exact execution and operator checks

Register the endpoint

Prepare a signed test event

Verify and deduplicate delivery

Run test:interoperability-conformance