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.
Each webhook delivery is an HTTP POST request with the following headers:
| Header | Description |
|---|
Content-Type | application/json |
User-Agent | paywise-webhooks/1.0 |
X-Paywise-Signature | HMAC SHA-256 signature (see Signature Verification) |
X-Paywise-Event | The event type (e.g. mandate.created) |
X-Paywise-Delivery-ID | Unique ID for this delivery attempt |
Payload Structure
{
"event": "mandate.created",
"timestamp": "2026-04-24T10:30:45.123456Z",
"data": {
"company_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"access_mode": "production",
...
}
}
| Field | Type | Description |
|---|
event | string | The event type that triggered this webhook |
timestamp | string | ISO 8601 timestamp of when the event was processed |
data | object | Event-specific payload |
data.company_id | string | UUID of the company this event belongs to |
data.access_mode | string | test or production |
Success Criteria
A delivery is considered successful when your endpoint returns any HTTP status code in the 2xx range (200–299).
Return HTTP 200 as quickly as possible. If you need to do heavy processing, acknowledge the webhook immediately and process the event asynchronously.
Timeouts
paywise waits up to 30 seconds for a response. If your endpoint does not respond within this window, the delivery is marked as failed and may be retried.
Redirects are not followed — your endpoint must return a 2xx response directly.
Retry Logic
Failed deliveries are automatically retried with exponential backoff:
| Attempt | Delay After Failure |
|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 15 minutes |
failed.
Delivery Statuses
| Status | Description |
|---|
pending | Delivery created, awaiting first attempt |
success | Endpoint returned a 2xx response |
retrying | Delivery failed but will be retried |
failed | All retry attempts exhausted |
Auto-Disable
Webhook endpoints track the number of consecutive failures across all deliveries. When the failure count reaches the configured threshold (default: 50), the endpoint is automatically disabled.
- Disabled endpoints stop receiving events entirely
- Re-enabling an endpoint (via API or dashboard) resets the failure counter to 0
- You can configure the threshold via the
max_consecutive_failures field (1–1000)
A single successful delivery resets the consecutive failure counter to 0. The auto-disable only triggers after an unbroken streak of failures.
Idempotency
Each delivery includes a unique idempotency_key derived from the webhook endpoint, event type, and timestamp. If you receive a delivery with the same idempotency key twice (which should be rare), you can safely skip the duplicate.
The delivery ID is also sent in the X-Paywise-Delivery-ID header for tracking purposes.
Best Practices
- Respond quickly — Return HTTP 200 immediately and process events asynchronously
- Verify signatures — Always validate the
X-Paywise-Signature header before processing
- Handle duplicates — Use the delivery ID or idempotency key to detect and skip duplicates
- Monitor failures — Check your endpoint’s failure count regularly via the API or dashboard
- Use test mode — Verify your integration using test events before subscribing to production events
