Skip to main content

Security and Signatures

This page documents signature verification using sealed contracts and fixtures.

Canonical sources:

  • Algorithm: docs/contracts/v1/rc96/webhook_signature_verification.md
  • Fixtures: docs/contracts/v1/rc96/fixtures/
  • Receiver samples: docs/contracts/v1/rc97/receiver-samples/
  • Packaged SDK (repo-local): docs/contracts/v1/rc98/sdk/

Normative Requirements​

  • Your receiver must verify signatures using the raw request body bytes (do not re-serialize JSON).
  • Your receiver must require X-Zex-Signature-Version: v1.
  • Your receiver must enforce timestamp tolerance using X-Zex-Timestamp (default tolerance is pinned by fixtures).

Required headers (v1)​

These header names are pinned by the RC-96 contract:

  • Content-Type: application/json
  • X-Zex-Timestamp
  • X-Zex-Event-Id
  • X-Zex-Signature-Version: v1
  • X-Zex-Signature

Rotation context (optional header):

  • X-Zex-Signature-Next

Quickstart (sealed sample code)​

Start from the sealed receiver samples:

  • Node: docs/contracts/v1/rc97/receiver-samples/node-express/
  • Python: docs/contracts/v1/rc97/receiver-samples/python-fastapi/

Reference fixtures:

  • docs/contracts/v1/rc96/fixtures/valid_signature.json
  • docs/contracts/v1/rc96/fixtures/invalid_signature.json