Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.paywise.de/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
X-Paywise-Signature: sha256=<hex_digest>
The <hex_digest> is the HMAC SHA-256 hash of the raw request body, computed using your endpoint’s secret key.

​
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

import hmac
import hashlib

def verify_webhook(request, secret_key):
    """Verify the webhook signature. Returns True if valid."""
    signature_header = request.headers.get('X-Paywise-Signature', '')
    if not signature_header.startswith('sha256='):
        return False

    received_signature = signature_header[7:]  # Strip 'sha256=' prefix
    expected_signature = hmac.new(
        secret_key.encode('utf-8'),
        request.body,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(received_signature, expected_signature)


# Usage in a Django view:
def webhook_handler(request):
    SECRET_KEY = "your-secret-key-here"

    if not verify_webhook(request, SECRET_KEY):
        return HttpResponse(status=401)

    payload = json.loads(request.body)
    event_type = payload['event']

    # Process the event...
    return HttpResponse(status=200)

​
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.