Webhooks

Solved outcome

What this enables

Use webhook delivery for notification and automation without promoting the envelope above the proof object it references.

Installed identity

@receiz/sdk

Version

124.1.0

Package SHA-256

479d52f4c2215b05377ac557a62427abae9c16347e5341201b72699311afd7ac

Record source

node_modules/@receiz/sdk/docs/webhook-signatures.md

Exact form

Signature or request

parseReceizWebhookRequest(request, { secret, toleranceSeconds: 300 })

Stable recovery

Failures

Permanent anchor · #webhooks-delivery-envelope

Delivery envelope

Read the unmodified raw body with x-receiz-signature and x-receiz-timestamp. The envelope declares receiz.webhook_event.v1 and references an underlying object for independent verification.

Permanent anchor · #webhooks-signature-verification

Signature verification

Call parseReceizWebhookRequest(request, { secret, toleranceSeconds: 300 }) before routing event data. Raw-body mutation, wrong secret, or timestamp failure rejects delivery mechanics.

Permanent anchor · #webhooks-event-schema

Event schema

Route only the installed receiz.webhook_event.v1 fields and event types. Do not infer ownership, settlement, or proof from event narration.

Permanent anchor · #webhooks-event-families

Event families

Use the installed event catalog and presets for payment, commerce, proof-settlement, and other declared families; unknown types remain explicit and unhandled.

Permanent anchor · #webhooks-secret-rotation

Secret rotation

Store the endpoint secret when issued or rotated, accept the declared overlap boundary, and remove retired secrets after the exact rotation window.

Permanent anchor · #webhooks-underlying-proof

Underlying proof

After authenticating delivery, independently verify the referenced sealed artifact; independently verify any claimed successor or register addition against its exact predecessor or head; and separately verify the claimed Ownership or Settlement state. Webhook authentication proves delivery, not the underlying claim.

Permanent anchor · #webhooks-end-to-end-example

End-to-end example

Apply the universal proof-object example to referenced artifact bytes after webhook authentication; never feed an envelope receipt into an authority-bearing API.

Copyable path

Authenticated SDK issuance → Verify → inspect receipt

import { createReceizClient } from "@receiz/sdk";

// Begin with the complete proof object already held by the person or runtime.
const encoded = process.env.RECEIZ_ARTIFACT_BASE64;
if (!encoded) throw new Error("RECEIZ_ARTIFACT_BASE64 is required");
const artifactBytes = Uint8Array.from(Buffer.from(encoded, "base64"));

// Local verification is account-free and precedes every transport projection.
const receiz = createReceizClient();
const verification = await receiz.verification.verifyArtifact(artifactBytes);
if (verification.status !== "verified-artifact") {
  throw new Error(`Artifact verification status: ${verification.status}`);
}
console.log(verification.status);