Why Verify Signatures?
Every webhook delivery includes anX-Paywise-Signature header containing an HMAC SHA-256 signature of the request body. You should always verify this signature to ensure that:
- The request was sent by paywise (not a third party)
- The payload has not been tampered with in transit
Signature Format
The signature header uses the following format:<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
