Delivery & Retries

Delivery Format

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

After 3 failed retry attempts, the delivery is permanently marked as 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

Integrations

Case Management API

Partner API

Delivery Format

Payload Structure

Success Criteria

Timeouts

Retry Logic

Delivery Statuses

Auto-Disable

Idempotency

Best Practices

​Delivery Format

​Payload Structure

​Success Criteria

​Timeouts

​Retry Logic

​Delivery Statuses

​Auto-Disable

​Idempotency

​Best Practices

Delivery Format

Payload Structure

Success Criteria

Timeouts

Retry Logic

Delivery Statuses

Auto-Disable

Idempotency

Best Practices