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

> [!NOTE]
>
> If no events are specified, Paybyrd subscribes to all available events.

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

> [!NOTE]
>
> If no payment methods are specified, Paybyrd subscribes to all available payment methods.

| 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

```bash Create 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"
    ]
}'
```

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

```bash Delete 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

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

```bash With pagination 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.