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

# Webhooks

> Receive real-time notifications when events occur in your account

## 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

<Steps>
  <Step title="Register an Endpoint">
    Create a webhook endpoint via the [API](/api-docs/case-management-api/webhooks/manage-endpoints) or in your [paywise dashboard](https://app.paywise.de/account/api/webhooks/). Provide an HTTPS URL and select the events you want to subscribe to.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receive Events">
    When a subscribed event occurs, paywise sends an HTTP POST request to your endpoint with the event payload and a signature header.
  </Step>

  <Step title="Verify & Process">
    Verify the `X-Paywise-Signature` header using your secret key, then process the event data.
  </Step>
</Steps>

## 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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Event Types" icon="bell" href="/api-docs/case-management-api/webhooks/event-types">
    See all available webhook event types and what triggers them
  </Card>

  <Card title="Signature Verification" icon="shield-check" href="/api-docs/case-management-api/webhooks/signature-verification">
    Learn how to verify webhook signatures to ensure authenticity
  </Card>

  <Card title="Manage Endpoints" icon="gear" href="/api-docs/case-management-api/webhooks/manage-endpoints">
    Create, list, and manage your webhook endpoints via the API
  </Card>

  <Card title="Delivery & Retries" icon="rotate" href="/api-docs/case-management-api/webhooks/delivery-and-retries">
    Understand the delivery mechanism, retry logic, and failure handling
  </Card>
</CardGroup>