Skip to main content

Overview

Pepay signs every webhook request so you can verify authenticity and integrity. Validation requires the raw request body plus the X-Pepay-Timestamp and signature headers.

Authentication

  • X-Pepay-Timestamp
  • X-Pepay-Signature
  • X-Pepay-Signature-Previous (optional during rotation)

Request

Signed payload format

  • ${timestamp_ms}.${raw_body}
  • Signature: HMAC_SHA256(secret, signed_payload) (hex)
Important:
  • Verify against the raw request body bytes, not a re-serialized JSON object.
  • Reject requests with timestamps outside a small tolerance window (recommended: 5 minutes).

Response

For successful verification, return a fast 2xx acknowledgment:

Errors

  • 400 invalid_signature when signature comparison fails.
  • 400 timestamp_out_of_range when the timestamp is outside your tolerance window.
  • Any non-2xx status can trigger retries from Pepay webhook delivery.

Examples

Node (no SDK)

SDK helper (Node)

See Webhooks (merchant) for the full SDK walkthrough.

Multiple endpoints and rotation

  • If you run multiple endpoints, keep a list of active secrets and verify against any.
  • Use X-Pepay-Network-Environment to route devnet vs mainnet endpoints if you want strict separation.
  • During rotation, keep the previous secret configured until all endpoints are updated.

Failure behavior

  • Return 2xx quickly after enqueueing work.
  • Non-2xx responses are retried with backoff, so keep handlers idempotent.
Next: WebSockets