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
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. |
| 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. |
| 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. |
| 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
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. |
Managing configurations
Create a configuration:
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: <YourAPIKey>' \
--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"
]
}'
curl --location 'https://webhook.paybyrd.com/api/v1/settings' \
--header 'x-api-key: <YourAPIKey>'
curl --location --request DELETE 'https://webhook.paybyrd.com/api/v1/settings/<WebhookSettingsId>' \
--header 'x-api-key: <YourAPIKey>'
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.
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:
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks?referenceId=<YourReferenceId>' \
--header 'x-api-key: <YourApiKey>'
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks' \
--header 'x-api-key: <YourApiKey>' \
--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:
curl --location 'https://webhook.paybyrd.com/api/v1/webhooks/resend' \
--header 'x-api-key: <YourApiKey>' \
--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 and open source on GitHub. 
