Webhook API

This document provides information on webhooks for Paybyrd. Webhooks allow you to receive real-time notifications about various events related to orders, transactions, payments, and more.

The API url is:
https://webhook.paybyrd.com

Authentication

To configure the webhook, authentication is required using an API Key. Include your API Key in the header of your HTTP request using the key x-api-key.

Example

Include the following header in your HTTP request to authenticate the webhook:

x-api-key: Your-API-Key

Replace Your-API-Key with the actual API Key provided by Paybyrd.

This API Key ensures secure and authorized communication between your system and the PayByrd webhook endpoint. Keep your API Key confidential and do not share it publicly.

Settings

The endpoint URL for configuration is:
https://webhook.paybyrd.com/api/v1/settings

Events

Below, we list various events that you can subscribe to for real-time notifications related to orders, transactions, and chargebacks.

If no events are specified in your configuration, Paybyrd will interpret it as a request to subscribe to all available events.

Orders

Order Creation and Status

Transactions

Preauthorization

Capture

Payment

Refund

Chargeback

Chargeback Lifecycle

Payment methods

Paybyrd supports various payment methods for transactions. When configuring your webhook, you can specify one or more of the following payment methods.

If no payment methods are specified in your configuration, Paybyrd will interpret it as a request to subscribe to all available payment methods.

Available Payment Methods

Webhook Authentication Credentials

When PayByrd sends requests to your specified webhook URL, it needs the appropriate credentials for secure and authorized communication. PayByrd supports two types of authentication credentials:

1. API Key

• Type: api-key
• Authentication Method: PayByrd includes an x-api-key in the request header.

To authenticate requests using an API Key, PayByrd adds a unique x-api-key to the request header. This acts as a secure identifier, allowing your webhook to verify the authenticity of incoming requests.

2. Basic Authentication

• Type: basic
• Authentication Method: PayByrd generates a username and password, sending them in basic authentication format.

For basic authentication, PayByrd generates a username and password combination. These credentials are sent in the request header using the basic authentication format, providing an additional layer of security.

How It works

• When you configure your webhook, you choose the desired authentication method.
• If you opt for an API Key, PayByrd generates an API key, sending it in the request header.
• If you choose basic authentication, PayByrd generates a username and password, sending them securely in the request header.

Examples

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
    ],
    "paymentMethods": [
        ...paymentMethods you want to subscribe
    ]
}'

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

Webhooks

Through the API, it's also possible to query the generated webhooks, check their status, review the responses obtained in each attempt, and even resend them if necessary.

The endpoint URL for webhooks is:
https://webhook.paybyrd.com/api/v1/webhooks

Query

When querying data through the API, you can use the following parameter:

Parameters

• referenceId: This parameter accepts either an OrderId, TransactionId, or ChargebackId. It serves as the source identifier for the webhook data you wish to retrieve. This means that when making a query, you provide the specific OrderId, TransactionId, or ChargebackId related to the webhook data you are interested in. The referenceId parameter allows you to narrow down and target your query to obtain precise information based on the unique identifier you provide.

Pagination

When working with a large dataset and needing to navigate through multiple pages of results, the API provides pagination support. To effectively iterate through these pages, utilize the following headers:

• x-page: Specify the page number you want to retrieve.
• x-page-size: Determine the length of each page.

Example:

If you set x-page to 2 and x-page-size to 10, you will receive results starting from the 11th record, allowing you to efficiently manage and retrieve the data in manageable chunks.

These headers enable you to control the flow of data retrieval, ensuring flexibility and efficiency when working with paginated API responses.

Webhook Response Ordering

To enhance clarity and convenience, our webhook responses are systematically ordered from the most recent to the oldest instances. This ordering principle ensures that when you review or retrieve webhook responses, you are presented with the latest data first.

Why Ordering Matters

1. Visibility of Recent Activity:

   • The most recent responses appear at the top of the list, providing immediate visibility into the latest webhook interactions.

2. Streamlined Analysis:

   • When analyzing webhook responses, the chronological ordering facilitates a more streamlined process, allowing you to focus on recent events before delving into historical data.

3. Efficient Debugging:

   • For debugging purposes, starting with the most recent responses allows for quicker identification of recent issues or successes, expediting the troubleshooting process.

Understanding this ordering principle enhances your experience in working with webhook responses, promoting efficient analysis and decision-making based on the most up-to-date information.

Examples

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: 7c051c9e-4506-4545-834f-af0d88863374' \
--header 'x-page-size: 25' \
--header 'x-page: 1'

Attempts

Our webhook engine is designed to ensure reliable delivery of webhooks by implementing an automatic retry mechanism. This process is crucial for maintaining communication integrity, especially in cases where the initial delivery attempt fails. Below are the key aspects of our retry strategy:

Automatic Retry Attempts:
Our system performs up to 50 automated retry attempts for each webhook delivery. These retries are systematically spaced to maximize the likelihood of successful delivery, even in temporary network issues or server unavailability.

Progressive Retry Delay:
The retry intervals are calculated using an arithmetic progression (AP) approach. The first retry is scheduled one minute after the initial failed attempt. Each subsequent retry increases the delay progressively, with the final (50th) attempt occurring 50 minutes after the initial attempt. In exceptional cases, where a specific delay threshold is required, the maximum delay between retries is capped at one hour.

Retry Trigger Conditions:
Any HTTP response code outside the 200 to 299 range is treated as an indication that a retry is necessary. This approach ensures that webhook delivery is only confirmed when a successful HTTP status code is received, reducing the risk of missed or incomplete communication.

By adhering to this structured retry mechanism, we enhance the reliability of our webhook service, ensuring that your systems receive the necessary notifications promptly, even when faced with transient errors.

Querying Webhook Attempts

After receiving a webhook, you may want to review all the attempts made for it. In such cases, you can access our attempts endpoint.

The endpoint URL for attempts is:
https://webhook.paybyrd.com/api/v1/webhooks/WEBHOOK_ID/attempts

This endpoint allows you to retrieve detailed information about the various attempts made for a specific webhook.

Pagination for Attempts

When dealing with a substantial amount of data from multiple attempts, efficient navigation becomes essential. The API supports pagination to help you manage and retrieve this information systematically. To make the most of this feature, consider the following headers:

• x-page: Specify the page number you wish to retrieve.
• x-page-size: Determine the length of each page.

Example:

If you set x-page to 2 and x-page-size to 10, you will receive results starting from the 11th attempt record. This facilitates a more organized and manageable approach to reviewing multiple attempts associated with a webhook.

Webhook Resending

If the need arises, you can resend specific webhooks.

Endpoint URL for Resending Webhooks:
https://webhook.paybyrd.com/api/v1/webhooks/resend

To resend webhooks, use the following curl command as an example:

curl --location 'https://webhook.paybyrd.com/api/v1/webhooks/resend' \
--header 'x-api-key: YourApiKey' \
--header 'Content-Type: application/json' \
--data '{
    "ids": [
        ...webhook ids you want to resend
    ]
}'

This example demonstrates how to structure a curl request to the resend endpoint. Ensure to replace 'YourApiKey' with your actual API key and provide the relevant webhook IDs in the "ids" array.

This functionality enables you to manually trigger the resend process for specific webhooks as needed.

Webhook Data Retention Policy

Our webhook data is subject to different retention periods based on the outcome of the webhook processing. For cases of failure, we retain webhook information for up to one month, encompassing all attempts made, as well as the payloads sent and received.

In the case of successful webhooks, the data is available for a more limited duration of one week, starting from the creation timestamp.

Data Retention Explanation

• Failure Cases:

  • Retention Period: Up to one month.
  • Details: Information includes all webhook attempts, along with the payloads sent and received during each attempt.

• Success Cases:

  • Retention Period: One week from the creation timestamp.
  • Details: Data is available for a more concise period, focusing on successful webhook instances.

Purge Routine Explanation

The routine of purging involves systematically removing webhook data that has surpassed its designated retention period. This process ensures that our data storage remains efficient, holding only the relevant information for the specified duration.

Understanding this retention policy helps users comprehend how long they can access webhook data and the circumstances that determine its availability. If there are specific data retrieval needs beyond these periods, alternative measures or queries to the API may be necessary.

Software Development Kit (SDK)

.Net (C#)

We offer a .NET SDK available on Nuget, and it's open source for the community on GitHub. This SDK simplifies integration, providing pre-built functionalities for easier development. If you prefer not to integrate manually, the SDK is a convenient option.