Skip to main content
This page documents a frozen v1 API. It receives only critical correctness or security corrections. For new integrations, use the current API and follow the linked migration guide.

Why Verify Signatures?

Every webhook delivery includes an X-Paywise-Signature header containing an HMAC SHA-256 signature of the request body. You should always verify this signature to ensure that:
  1. The request was sent by paywise (not a third party)
  2. The payload has not been tampered with in transit
Never process webhook events without verifying the signature first. Skipping verification exposes your application to forged requests.

Signature Format

The signature header uses the following format:
The <hex_digest> is the HMAC SHA-256 hash of the raw request body, computed using your endpoint’s secret key. paywise sends the body as compact JSON with sorted keys. Compute the hash over the raw bytes exactly as received: parsing and re-serializing the JSON produces different bytes and a signature mismatch.

Verification Steps

1

Extract the Signature

Read the X-Paywise-Signature header and strip the sha256= prefix.
2

Compute the Expected Signature

Calculate the HMAC SHA-256 hash of the raw request body using your secret key.
3

Compare

Use a constant-time comparison function to compare the received and expected signatures. Return HTTP 401 if they don’t match.

Code Examples

Secret Key

  • The secret key is generated automatically when you create a webhook endpoint
  • It is displayed only once at creation time — save it immediately
  • The key is a 44-character cryptographically secure random string
  • If you lose your secret key, delete the endpoint and create a new one
Store your webhook secret key in environment variables or a secrets manager — never hard-code it in your application source code.