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.

​
What are Webhooks?

Webhooks allow you to receive real-time HTTP POST notifications when events occur in your paywise account. Instead of polling the API for changes, webhooks push updates directly to your server as they happen. When an event occurs (e.g. a mandate is created or a payment is reported), paywise sends an HTTP POST request to your configured endpoint URL with a JSON payload describing the event.

​
How it Works

1

Register an Endpoint

Create a webhook endpoint via the API or in your paywise dashboard. Provide an HTTPS URL and select the events you want to subscribe to.
2

Save Your Secret Key

When you create an endpoint, a unique secret key is generated and displayed once. Save it securely — you will need it to verify webhook signatures.
3

Receive Events

When a subscribed event occurs, paywise sends an HTTP POST request to your endpoint with the event payload and a signature header.
4

Verify & Process

Verify the X-Paywise-Signature header using your secret key, then process the event data.

​
Key Features

  • HTTPS only — Webhook URLs must use HTTPS for security
  • Signed payloads — Every delivery includes an HMAC SHA-256 signature for authenticity verification
  • Automatic retries — Failed deliveries are retried up to 3 times with exponential backoff
  • Auto-disable — Endpoints are automatically disabled after too many consecutive failures (default: 50)
  • Access mode isolation — Test and production webhooks are strictly separated
  • Test events — Send test events to verify your integration before going live

​
Quick Example

A webhook delivery looks like this: 
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: paywise-webhooks/1.0
X-Paywise-Signature: sha256=5d7c4e...
X-Paywise-Event: mandate.created
X-Paywise-Delivery-ID: a1b2c3d4-...

{
  "event": "mandate.created",
  "timestamp": "2026-04-24T10:30:45.123456Z",
  "data": {
    "company_id": "...",
    "access_mode": "production",
    ...
  }
}

​
Next Steps

Event Types

See all available webhook event types and what triggers them

Signature Verification

Learn how to verify webhook signatures to ensure authenticity

Manage Endpoints

Create, list, and manage your webhook endpoints via the API

Delivery & Retries

Understand the delivery mechanism, retry logic, and failure handling