> ## Documentation Index
> Fetch the complete documentation index at: https://docs.papp.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Management

> Create, list, update, and delete webhook endpoints

Points lets each merchant manage webhook endpoints over the API.

Available operations:

* `GET /v1/webhooks`
* `POST /v1/webhooks`
* `GET /v1/webhooks/{uuid}`
* `PUT / PATCH /v1/webhooks/{uuid}`
* `DELETE /v1/webhooks/{uuid}`

All webhook management endpoints require `x-api-key`.

## Create

```bash theme={null}
curl -X POST https://business.papp.sa/api/v1/webhooks \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Notifications",
    "url": "https://merchant.example.com/webhooks/points"
  }'
```

Response fields include:

* `uuid`
* `merchant_id`
* `name`
* `url`
* `secret`
* `created_at`
* `updated_at`

<Warning>
  Persist the returned `secret` securely at creation time. Your webhook consumer needs it to verify authenticity.
</Warning>

## List

```bash theme={null}
curl https://business.papp.sa/api/v1/webhooks \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Accept: application/json"
```

Current backend behavior paginates the results. You can pass `per_page`.

## Retrieve one webhook

```bash theme={null}
curl https://business.papp.sa/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Accept: application/json"
```

## Update

```bash theme={null}
curl -X PATCH https://business.papp.sa/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Order Webhook",
    "url": "https://merchant.example.com/webhooks/points-v2"
  }'
```

## Delete

```bash theme={null}
curl -X DELETE https://business.papp.sa/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: $POINTS_API_KEY"
```

## Validation and operational rules

| Rule                                   | Current behavior                    |
| -------------------------------------- | ----------------------------------- |
| Merchant must be verified/published    | Required for create, update, delete |
| URL must be valid                      | Enforced                            |
| Duplicate URL for same merchant        | Rejected                            |
| Wrong merchant tries to access webhook | Returns not found                   |

## Recommended operational model

* one primary webhook URL per environment
* optionally one additional audit or dead-letter endpoint
* avoid pointing the same merchant to too many downstream consumers unless you truly need fan-out

## Dashboard vs API

You can manage webhooks through the Business dashboard or the API. The API is recommended if you want repeatable environment setup through scripts.

See [Webhooks overview](/webhooks/overview#register-a-webhook) for the quickstart example and [API reference](/api-reference) for schema details.