Webhooks

In this article, you will learn how to add and manage webhooks in Payrexx to communicate with third-party systems.

What is a Webhook?

A webhook allows one application to communicate with another application and provide it with information in real-time. For example, Application A can send a notification to Application B when a specific event occurs.

In the context of Payrexx, webhooks can be used to synchronize transactions and their status with third-party systems such as an e-commerce system or content management software.

There are plugins available for various e-commerce systems for integrating with Payrexx. If the integration is done through such a plugin, it is not necessary to create a webhook.

Creating a Webhook

To create a webhook, log into your Payrexx account and navigate to Webhooks in the main menu of the merchant administration.

Next, click the white "Add Webhook" button, which will open the following window:

[IMAGE]

Legend: Configuring a webhook in Payrexx

1. Name: Assign any name to the webhook. This is solely for your reference to easily identify the webhook if you create multiple webhooks.

2. Webhook URL: Enter the URL to which the webhook should be sent. Ensure that the URL is entered correctly. Often, you will receive the URL to be entered from the third-party system you are integrating with.

3. Events: Define the event or events that should trigger the webhook. The available types are "Transaction," "Subscription," and "Payout". More information can be found in the "Types of webhooks" section.

4. Retry on Failure: There may be instances where the webhook triggers an error at the webhook URL. By activating this checkbox, you ensure that the webhook will be retried in such cases. The attempt to send the webhook will be repeated up to 10 times.

Payrexx recommends activating this option only if required by the third-party system being integrated.

1. Webhook Type: Choose whether the communication between Payrexx and the third-party system should use the "PHP-Post" or "JSON" format.

2. Webhook Version: Select the correct version of the webhook. This information can be found in the integration guide of the respective e-commerce system, CMS, or enterprise software tool.

3. Send Test Data: Send a test transaction to verify if the webhook is configured correctly.

4. Create Webhook: Click "Add" to complete the configuration and create the webhook.

Types of webhooks

Payrexx offers the following three types of webhooks:

Transaction

Triggered when a transaction is created or when the status of a transaction changes.

Subscription

Triggered when an important event occurs in a subscription managed by Payrexx.

Payout

Triggered when a new payout is initiated in Payrexx.

Overview of Created Webhooks

If you have already created webhooks in Payrexx, you can find them by navigating to Webhooks in the main menu of your merchant administration:

[IMAGE]

Legend: Two registered webhooks for FLOW Shopsoftware and PrestaShop

Webhook Errors

When communicating between two systems via webhooks, errors can occur. Such webhook errors typically happen when the target system rejects a request or the processing of the webhook in the target system triggers an error.

The cause of webhook errors usually lies within the target system. However, they can also stem from an incorrect webhook URL or an incorrect webhook content type.

In the following section, we will show you solutions for the most common webhook errors.

Webhook errors with plugins

Plugins are available for integrating Payrexx with various e-commerce systems. If webhook errors occur in one of these integrations, we recommend the following steps:

1. Carefully read the documentation for the respective e-commerce integration, paying particular attention to the "Configuring Payrexx" section.

2. Ensure that the entered webhook URL is correct. A common error is that the spelling of the entered webhook URL does not match that of the target system. Example: https://mypage.com/payrexx-webhook versus https://www.mypage.com/payrexx-webhook

If you cannot find the error, create a support ticket and provide us with the following information:

• Instance name in Payrexx

• Webhook URL

• Access credentials for the administration area of your third-party system

Errors with custom webhooks

If you have not used a plugin for the integration but have instead created a webhook manually, we advise you to check the logs in case of webhook errors.

• To do this, navigate to Webhooks and click "Logs" next to the relevant webhook:

[IMAGE]

Legend: Opening the logs of a webhook in Payrexx

• Next, click on the entry in the list of webhook requests that you want to investigate:

[IMAGE]

Legend: List of sent webhooks including status

• On the right side of the screen, you will now see all the details related to the corresponding webhook request:

[IMAGE]

Legend: Details of a webhook request

• If you scroll down, you will find the HTTP status of the webhook request:

[IMAGE]

Legend: Webhook request with HTTP Status 0

The HTTP status is a response from the target server, returned to the sender of the webhook (in this case, Payrexx) in the form of a numerical code. This returned value helps you identify the problem and determine how to resolve it:

Webhook error with HTTP Status 0

A webhook error with HTTP Status 0 typically occurs when the target server (Webhook URL) does not respond to Payrexx's request within 20 seconds.

Solutions:

• Ask your technical specialist to optimize the performance of your server.

• Enable the "Retry on Failure" option for the webhook in Payrexx, so the request will be resent in case of a failed webhook.

Webhook error with HTTP Status 301

A webhook error with HTTP Status 301 typically occurs when a page has been permanently moved to a new location. This is usually the case when the domain name or URL structure of a website has changed.

Solutions:

• If you have made such changes, you will need to update them in Payrexx as well, so that the webhooks can be sent and responded to again.

• Clear your browser cache and try again.

Webhook error with HTTP Status 302

A webhook error with HTTP Status 302 typically occurs when the merchant server, to which Payrexx sends the webhook, is temporarily unreachable.

Solutions:

• Ask your technical contact to check if the webhook is set up correctly.

• Ask your technical contact to investigate what might be causing the limited accessibility of the server.

Webhook error with HTTP Status 403

A webhook error with HTTP Status 403 typically occurs when the URL specified in the webhook does not point to a shop. Another reason could be a lack of permission to execute the webhook.

Solutions:

• Ensure that the URL recorded in the webhook correctly points to the shop.

• Ask your server provider to whitelist the webhook's IP addresses (3.79.212.4, 3.73.29.220) to allow permission for the execution of the webhook.

Webhook error with HTTP Status 404

A webhook error with HTTP Status 404 typically occurs when the resource requested by the webhook cannot be found on the merchant's server. Possible reasons include:

• The URL specified in the webhook is incorrect.

• The URL specified in the webhook has been deleted or moved.

• The transaction referenced by the sent webhook no longer exists on the merchant's server.

Solutions:

• Check if the URL recorded in the webhook is still correct.

• If the order is no longer available, ignore the webhook error.

Webhook error with HTTP Status 500

A webhook error with HTTP status 500 typically occurs when the merchant's server fails to provide a valid response to the request sent by Payrexx. Possible causes include:

• The URL to the merchant's server stored in Payrexx is incorrect.

• The server accepts the webhook but fails to process the data. In this case, you should check the log files of your server for more information.

• The merchant's server was temporarily unreachable at the time of the request.

• The error is caused by an incorrect format (JSON/Post Form Data).

Solutions:

• Check the URL you have entered for the webhook in Payrexx.

• Verify with your specialists the availability of your server.

• Change the format of the webhook (JSON/Post Form Data) and try again.

If you cannot find the error, create a support ticket and provide us with the following information:

• Instance name in Payrexx

• Webhook URL

• Access credentials for the administration area of your third-party system

Information for Developers

Additional technical information about webhooks can be found in the relevant article in our developer documentation:

WebhookDeveloper