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

# Configure Webhook

> Set or update the webhook endpoint URL and subscribe to specific events

## Authentication

This endpoint requires a **Bearer token** in the `Authorization` header.

```
Authorization: Bearer <your_jwt_token>
```

## Body Parameters

<ParamField body="url" type="string" required>
  The HTTPS URL that will receive webhook POST requests. Must be publicly accessible.
</ParamField>

<ParamField body="events" type="array">
  An array of event types to subscribe to. If omitted, the webhook will receive all events.

  Supported events:

  * `payment.completed` - A payment has been confirmed on-chain
  * `payment.failed` - A payment failed due to underpayment or error
  * `payment.expired` - A payment expired before receiving funds
  * `subscription.renewed` - A recurring subscription payment was collected
  * `subscription.cancelled` - A subscription was cancelled
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the webhook configuration.
</ResponseField>

<ResponseField name="url" type="string">
  The configured webhook URL.
</ResponseField>

<ResponseField name="events" type="array">
  The list of subscribed event types.
</ResponseField>

<ResponseField name="active" type="boolean">
  Whether the webhook is currently active.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the webhook was configured.
</ResponseField>

<Info>
  Webhook payloads are signed with ED25519. Use the [Get Public Key](/api-reference/webhooks/get-public-key) endpoint to retrieve the verification key.
</Info>

<RequestExample>
  ```json Request theme={null}
  {
    "url": "https://yoursite.com/webhooks/openpay",
    "events": [
      "payment.completed",
      "payment.failed",
      "payment.expired"
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "wh_abc123def456",
    "url": "https://yoursite.com/webhooks/openpay",
    "events": [
      "payment.completed",
      "payment.failed",
      "payment.expired"
    ],
    "active": true,
    "createdAt": "2026-03-26T14:30:00Z"
  }
  ```
</ResponseExample>