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

# Webhook API

Webhooks deliver real-time notifications about events related to orders, transactions, and chargebacks.

**Base URL:** `https://webhook.paybyrd.com`

## Authentication

Authenticate all requests with your API key in the `x-api-key` request header.

## Settings

Configure webhook subscriptions at `https://webhook.paybyrd.com/api/v1/settings`.

### Events

<Info>If no events are specified, Paybyrd subscribes to all available events.</Info>

#### Orders

| Event                 | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| order.created         | A new order was created.                                       |
| order.pending         | The order is awaiting further action or confirmation.          |
| order.paid            | The order has been fully paid.                                 |
| order.refunded        | The order amount was refunded.                                 |
| order.canceled        | The order was canceled.                                        |
| order.expired         | The order expired without a completed payment.                 |
| order.temporaryfailed | A temporary failure occurred during the order payment process. |

#### Transactions

**Pre-authorisation**

| Event                        | Description                                 |
| ---------------------------- | ------------------------------------------- |
| transaction.preauth.pending  | Pre-authorisation is awaiting approval.     |
| transaction.preauth.success  | Pre-authorisation was approved.             |
| transaction.preauth.failed   | Pre-authorisation failed.                   |
| transaction.preauth.error    | An error occurred during pre-authorisation. |
| transaction.preauth.canceled | Pre-authorisation was canceled.             |

**Capture**

| Event                        | Description                       |
| ---------------------------- | --------------------------------- |
| transaction.capture.pending  | Capture is awaiting confirmation. |
| transaction.capture.success  | Capture completed successfully.   |
| transaction.capture.failed   | Capture failed.                   |
| transaction.capture.error    | An error occurred during capture. |
| transaction.capture.canceled | Capture was canceled.             |

**Payment**

| Event                        | Description                       |
| ---------------------------- | --------------------------------- |
| transaction.payment.pending  | Payment is awaiting confirmation. |
| transaction.payment.success  | Payment completed successfully.   |
| transaction.payment.failed   | Payment failed.                   |
| transaction.payment.error    | An error occurred during payment. |
| transaction.payment.canceled | Payment was canceled.             |

**Refund**

| Event                       | Description                      |
| --------------------------- | -------------------------------- |
| transaction.refund.pending  | Refund is awaiting confirmation. |
| transaction.refund.success  | Refund completed successfully.   |
| transaction.refund.failed   | Refund failed.                   |
| transaction.refund.error    | An error occurred during refund. |
| transaction.refund.canceled | Refund was canceled.             |

#### Chargebacks

| Event                    | Description                             |
| ------------------------ | --------------------------------------- |
| chargeback.created       | A chargeback was initiated.             |
| chargeback.disputing     | The chargeback is being disputed.       |
| chargeback.pendingaction | The chargeback requires further action. |
| chargeback.closed        | The chargeback case was closed.         |
| chargeback.won           | The chargeback dispute was won.         |
| chargeback.lost          | The chargeback dispute was lost.        |

### Payment methods

<Info>If no payment methods are specified, Paybyrd subscribes to all available payment methods.</Info>

| Payment method | Description                                 |
| -------------- | ------------------------------------------- |
| card           | Credit or debit card transactions.          |
| ideal          | iDEAL transactions (Netherlands).           |
| multibanco     | Multibanco transactions (Portugal).         |
| mbway          | MB WAY transactions (Portugal).             |
| multicaixa     | Multicaixa transactions (Angola).           |
| pickup         | In-store or designated pickup transactions. |
| paypal         | PayPal transactions.                        |
| banktransfer   | Bank transfers.                             |
| floa           | Floa transactions.                          |
| pix            | Pix instant payment transactions (Brazil).  |

### Webhook authentication

When Paybyrd sends requests to your webhook URL, it authenticates them using one of two credential types:

| Type    | Value     | How it works                                                                                                    |
| ------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| API Key | `api-key` | Paybyrd adds an `x-api-key` header to each request.                                                             |
| Basic   | `basic`   | Paybyrd generates a username and password sent in the `Authorization` header using Basic authentication format. |

You select the credential type when creating the webhook configuration.

### Managing configurations

**Create a configuration:**

```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "url": "<YourWebhookURL>",
    "credentialType": "<DesiredCredentialType>",
    "events": [
        "...events you want to subscribe to"
    ],
    "paymentMethods": [
        "...payment methods you want to subscribe to"
    ]
}'
```

**List configurations:**

```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: {your_api_key}'
```

**Delete a configuration:**

```bash theme={null}
curl --location --request DELETE 'https://webhook.paybyrd.com/api/v1/settings/<WebhookSettingsId>' \
--header 'x-api-key: {your_api_key}'
```

## Querying webhooks

Query generated webhooks, check their status, review attempt responses, and resend them at `https://webhook.paybyrd.com/api/v1/webhooks`.

### Parameters

* **`referenceId`**: An `orderId`, `transactionId`, or `chargebackId`. Filters results to webhooks associated with that entity.

### Pagination

Use the following request headers to paginate results:

* **`x-page`**: Page number to retrieve.
* **`x-page-size`**: Number of results per page.

Results are ordered from most recent to oldest.

### Examples

**Query by referenceId:**

```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks?referenceId=<YourReferenceId>' \
--header 'x-api-key: {your_api_key}'
```

**Query with pagination:**

```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks' \
--header 'x-api-key: {your_api_key}' \
--header 'x-page-size: 25' \
--header 'x-page: 1'
```

## Retry behaviour

The webhook engine retries failed deliveries automatically. Any HTTP response outside the `2xx` range is treated as a failure and triggers a retry.

* Up to **50 retry attempts** per webhook.
* Retry intervals follow an arithmetic progression: the first retry is 1 minute after the failed attempt, increasing by 1 minute per retry, up to a maximum delay of 1 hour.

## Querying attempts

Retrieve the attempt history for a specific webhook:

`GET https://webhook.paybyrd.com/api/v1/webhooks/{webhookId}/attempts`

Pagination is supported using the same `x-page` and `x-page-size` headers described above.

## Resending webhooks

Manually resend one or more webhooks:

```bash theme={null}
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks/resend' \
--header 'x-api-key: {your_api_key}' \
--header 'Content-Type: application/json' \
--data '{
    "ids": [
        "...webhook IDs to resend"
    ]
}'
```

## Data retention

| Outcome             | Retention period                                         |
| ------------------- | -------------------------------------------------------- |
| Failed webhooks     | Up to 1 month (all attempts, payloads sent and received) |
| Successful webhooks | 1 week from creation timestamp                           |

## SDK

A .NET SDK is available on [NuGet](https://www.nuget.org/packages/Paybyrd.Clients.Webhook) and open source on [GitHub](https://github.com/paybyrd/paybyrd-clients-dotnet).