This site requires javascript to be enabled.

Webhooks

Results for

Results for search.results.searching

Webhooks notify you about events that occur with regards to the payments that you process via Worldline, like status changes on payments. You can select which type of events you want to be notified about and where we should send them to. This allows you to be easily aware of things that happen, even after the consumer is no longer on your site.

When to use webhooks?

You want to be informed whenever an event occurs in your Worldline account. Webhooks provide this information by making a POST request to one or more HTTPS endpoints on your server. Events can be triggered in two ways:

  • Directly from an API call you make events of this type only add a little value since you'll be informed about them via the API response anyway.
  • Something "out of your sight" events of this type are more interesting to have webhooks notifications enabled.

Let's take a look at an example. The online authorization of a redirect payment only happens after the consumer finishes the process at the 3rd party provider. This action is not visible to you as the consumer is not on your website. You could periodically check the current payment status using our API ("poll"), but it's not very efficient. Using webhooks, however, you can subscribe to one or more payment events, which will trigger us to make a POST request to an HTTPS endpoint on your server when the payment status changes. Or, in webhooks terms, when the "event occurs."

We'll include the complete JSON payment object in that message so you have all relevant information directly at hand.

Currently, we support events that happen on payments, payouts, and refunds. Please check the webhooks event types to see all events that webhooks can inform you about.

Before you start using webhooks

  1. Configure webhooks in the Configuration Center. This way we know which events you're interested in and to which endpoints we should send them.
  2. Set up your webhooks endpoint. It means that you need to build an application that handles incoming webhooks events and run that on an HTTPS endpoint on your server. Our server SDKs can help you with common tasks like translating the JSON into objects and signature verification. Please also notice the S in HTTPS, since we only support encrypted communication. Your application should be able to:
    • respond to get GET action and echo the 'X-GCS-Webhooks-Endpoint-Verification' header value in the body
    • respond to the POST action with a 2XX status code for all events delivered
    • validate the signature on the message

Configuring webhooks in the Configuration Center

  1. Create a webhooks key.

You can do this in the Configuration Center on the "webhooks keys" page. Click on the "request webhooks key" button. Just like with the API key, it's used to sign the messages that are sent between you and us.

In the webhooks case we sign the message and you should verify the signature to make sure that it was indeed sent by us. Verification of the signature occurs automatically if you use one of our server SDKs, or plugins. Since webhooks keys are defined per account they are used to sign the messages of all our listed merchant IDs. You do not need to create a webhooks key per merchant ID.

weebhooks-keys

  1. Add one or more webhooks endpoints.

If you have more than one merchant ID connected to your account then first select the merchant ID for which you would like to add an endpoint. Then open the "webhooks" page, and click on the "add endpoint" button. Provide the endpoint's secure (HTTPS) URL and select which type of events it needs to receive. You can either choose to subscribe to all event types or to a subset that you can select in the popup as well.

weebhooks-keys

To ensure the URL is a valid webhooks endpoint, we send an HTTPS GET request to it as soon as it's created. This request includes a random string in the "X-GCS-Webhooks-Endpoint-Verification" HTTP header. The endpoint's response should be a plain text body containing only this header's value.

If your endpoint fails to do this, it will still be added to your list of endpoints as deactivated. If this happens, you can fix the issue on your end and then use the endpoint's "activate" action later, which will trigger the validation call again. The endpoint will start receiving messages a couple of minutes after it has been successfully activated.

weebhooks-activate-endpoint

  • You can add up a maximum of five endpoints per merchant ID. You can only have one endpoint subscribed to a specific event.
  • Webhooks can take up to 10 minutes to react to changes you made in the Configuration Center.
  • Please see the FAQ below for more details on configuring webhooks.

Setting up your webhooks endpoint

The webhooks messages will be sent to your endpoints via HTTPS POST requests. The request's body contains JSON that describes the event and the object on which the event occurred. These objects' structure is identical to those that are returned in our REST API. For instance, the "payment" object in a webhooks message is identical to the object returned by the GET payment REST endpoint. See the webhooks event structure for a detailed explanation of the webhooks message.

To handle these incoming messages, you should set up your server to perceive both POST and GET requests on the endpoints you've set up in the Configuration Center:

  • POST – to handle the actual messages
  • GET – for the URL validation, as mentioned in the previous section

The way it's done depends on your server technology. If you're using one of our plugins, you can simply use the plugin's configuration page to set this up.

prestashop webhooksThe PrestaShop webhooks screen where merchants can configure the webhooks keys. 

If you cannot use one of the plugins, you should configure the framework you're using to perceive the endpoints and pass the request to our SDK. The SDK will check the signature and return an actual object instead of the JSON included in the request. You can then pass this data to your own business logic.

Responding to a webhooks event

All successfully received webhooks messages should return an HTTP status code in the 2xx range. Any additional information in the body or header is ignored. Whenever an endpoint responds with a status code out of that range, webhooks assume that your endpoint didn't receive the message and will retry later. It means that HTTP redirects, which are 3xx codes, will also fail. See "retrying failed events" for more information on how webhooks perform retries.

If an endpoint doesn't respond within 10 seconds, webhooks will also assume your endpoint didn't receive the message, and we'll retry later. To prevent this, it's important to decouple as much of your business logic from the handling of the request as possible. Please respond with a 2xx HTTP status code immediately after receiving the message and handle all other tasks afterward.

Testing webhooks endpoints

Now, you can use the Сonfiguration Сenter to test your endpoints. Select your desired merchant ID, and go to the "Webhooks" page. You can choose the endpoint you want to test, click the "Actions" dropdown menu, and select "Test." This action will result in webhooks executing a POST request to that endpoint with a dummy event.

In the popup, you can see whether the test was successful or something went wrong. Successful means that we could reach your endpoint, and it responded with the expected 2xx status code before the request timed out. The popup also shows you the request we made, the response we received from the endpoint, and how long it took for the endpoint to reply.

/webhooks-test-endpoint

weebhooks-endpoint-test-results

Common issues found while testing

Issue Solution
An endpoint redirect to a different URL using an HTTP 30x status code. Webhooks does not accept redirects. The required response status code needs to be in the 2xx range.
The request times out before the endpoints return a response.

Make sure your endpoint responds within 10 seconds.

The test described above only checks if webhooks can reach the endpoint. To test if an endpoint handles the different event types correctly, you need to use our REST API to make calls that trigger the desired event. For example, if you want to test handling a "captured" event on a payment object, create a payment using the REST API to trigger a "captured" event. You can use our pre-production environment to make these test calls without actually making payments.

Operational considerations

We'll send events to the endpoints as quickly as possible, typically a few seconds after occurrence. The first delivery attempt will occur within 24 hours of the event's creation time. In rare circumstances, the delivery may take longer.

Some known limitations are:

  • The sequence of events we send may not always match the order in which they happened. While they are generally in order, there are instances where this may not be the case. For example, if the initial delivery of an event fails and a second event succeeds before a retry, the order may vary.
  • An event may be sent multiple times. To prevent duplicates, you can ensure that the unique ID assigned to each event has not been processed before.

How webhooks will retry failed deliveries of events

Whenever an endpoint doesn't successfully receive a message, two things will happen:

  1. If an endpoint fails too often, we stop sending messages to it by temporarily blacklisting the endpoint.
  2. We'll retry to send the failed message and all skipped messages later.

Blacklisting

If five consecutive messages cannot be delivered to an endpoint, we'll temporarily stop sending messages to that endpoint for 5 minutes. This is referred to as "blacklisting the endpoint." Any messages that were supposed to be sent during the blacklisting period will be sent later through the retry mechanism.

We use blacklisting because it's probable that the endpoint is either offline or overloaded, and it typically takes a few minutes for it to become operational again. Attempting to send messages during this period would likely lead to failed deliveries, further overloading the already troubled endpoint.

Retrying failed messages

We will make multiple attempts to deliver each unsuccessful message, and with each unsuccessful attempt, we will increase the delay before resending the message. The schedule below outlines the retry times in relation to the initial delivery attempt. For example, the 7th retry will occur 8 hours after the first attempt to send the event to the endpoint. The 8th retry will then take place another 8 hours later, making it a total of 16 hours since our initial attempt.

Retry attempt Retry time relative to first delivery attempt
1 immediately 
2 5 minutes
3 1 hour
4 2 hours
5 4 hours
6 6 hours
7 8 hours
8 16 hours
9 24 hours
10 48 hours

After 10 retry attempts, which equates to 48 hours from our initial try, we classify an event as undeliverable. While we currently don't provide a manual option for resending events, you can use our REST API to check the status of the specific objects you're concerned about.

FAQ