Webhooks Overview

Webhooks are optional integration surfaces for event delivery.

This guide is pinned to sealed contracts and fixtures in this repo. Canonical sources:

• Event catalog: docs/contracts/v1/webhooks/rc79/event_catalog_v1_1.md
• Envelope schema: docs/contracts/v1/rc96/webhook_envelope.schema.json
• Signature algorithm + fixtures: docs/contracts/v1/rc96/
• Receiver samples: docs/contracts/v1/rc97/
• Packaged SDK (repo-local): docs/contracts/v1/rc98/
• Merchant harness (offline): docs/contracts/v1/webhooks/rc99/

Normative Requirements

• Your receiver must treat the request body as bytes for signature verification.
• Your receiver should deduplicate business processing by event_id (header X-Zex-Event-Id).
• Your receiver should be able to handle retries and replays without creating duplicate side effects.

Envelope shape (consumer view)

Webhook payloads are JSON objects. The canonical schema is:

• docs/contracts/v1/rc96/webhook_envelope.schema.json

Example envelope:

• docs/contracts/v1/rc100/fixtures/event_envelope_example.json