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

# Manage Endpoints

> Create, update, and manage your webhook endpoints

## Creating a Webhook Endpoint

### Via API

```bash theme={null}
curl -X POST https://api.paywise.de/v1/webhooks/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks",
    "events": ["mandate.created", "mandate.status_updated", "payment.created"],
    "description": "Production Server"
  }'
```

**Response** (201 Created):

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-domain.com/webhooks",
  "enabled": true,
  "events": ["mandate.created", "mandate.status_updated", "payment.created"],
  "access_mode": "production",
  "secret_key": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789_abc",
  "description": "Production Server",
  "max_consecutive_failures": 50,
  "consecutive_failures": 0,
  "last_failure_at": null,
  "created": "2026-04-24T10:30:45.123456Z",
  "updated": "2026-04-24T10:30:45.123456Z"
}
```

<Warning>
  The `secret_key` is only included in the response when creating an endpoint. Save it immediately — it cannot be retrieved later.
</Warning>

### Via Dashboard

You can also manage webhooks in your [paywise dashboard](https://app.paywise.de/account/api/webhooks/).

## API Reference

### List Endpoints

```bash theme={null}
GET /v1/webhooks/
```

Returns all webhook endpoints for your company. Optionally filter by status:

```bash theme={null}
GET /v1/webhooks/?enabled=true
```

### Retrieve an Endpoint

```bash theme={null}
GET /v1/webhooks/{id}/
```

### Update an Endpoint

```bash theme={null}
PATCH /v1/webhooks/{id}/
```

Update any writable field. For example, to add a new event subscription:

```bash theme={null}
curl -X PATCH https://api.paywise.de/v1/webhooks/{id}/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["mandate.created", "mandate.status_updated", "payment.created", "mandate.closed"]
  }'
```

**Writable fields:**

* `url` — Endpoint URL (must be HTTPS)
* `enabled` — Enable or disable the endpoint
* `events` — List of subscribed event types
* `description` — Optional description
* `max_consecutive_failures` — Auto-disable threshold (1–1000)

### Delete an Endpoint

```bash theme={null}
DELETE /v1/webhooks/{id}/
```

### Send a Test Event

Send a test event to verify your endpoint is working correctly:

```bash theme={null}
POST /v1/webhooks/{id}/test/
```

```json theme={null}
{
  "event_type": "mandate.created"
}
```

The test event will be delivered with `"test": true` in the payload.

### List Deliveries

View delivery history for a specific endpoint:

```bash theme={null}
GET /v1/webhooks/{id}/deliveries/
```

Or list all deliveries across all endpoints:

```bash theme={null}
GET /v1/webhook-deliveries/
GET /v1/webhook-deliveries/?status=failed&event_type=mandate.created
```

**Delivery statuses:** `pending`, `success`, `failed`, `retrying`