Webhooks

We can't guarantee that webhook notifications will arrive instantly. We strive to send them as quickly as possible, but the delivery time can vary. This depends on the number of messages in the queue and how quickly a webhook notification is acknowledged. Delivery times can range from seconds to hours.

The events on Payment will help you out as

• on the GlobalCollect platform we have included the hostedCheckoutId in hostedCheckoutSpecificOutput if the payment was done through the myCheckOut hosted pages.
• on the Ogone platform we have included the merchantReference in createHostedCheckoutResponse and hence this field can be used to link with the merchantReference in createPaymentResponse.payment.paymentOutput.references if the payment was done through the myCheckOut hosted pages.

The messages will be signed with the key that has been added first, so the oldest key is what we'll use. If we would use the most recently created key we could break the system since you would not have had time to configure the new key on your servers yet. The safest way to incorporate this on your end is to look at the request's X-GCS-KeyId HTTP header which contains the key id of the key that we used to sign the message. You can look up the secret key in your own configuration based on that key id.

For security it's best to have "separate keys for separate things". Signing REST API calls and verifying the signature of webhooks messages are two different things each with their own level of sensitivity. Having two keys allows you to handle signing REST API calls and verifying webhooks messages on different machines (with perhaps different security measures in place) without having to deploy a single "superkey" on both systems. It also allows us to handle the keys differently, as we for instance do with respect to the expiration time: the webhooks key does not expire, but the REST API key does. 

Since the REST API calls can contain sensitive card information PCI/DSS requires us to use keys that expire. Adding an expiration date to a key requires you to periodically change these keys, so it increases the complexity of your operational processes. Since the webhooks messages do not contain any sensitive card information we decided to not use expiration dates on the webhooks keys so we can keep the webhooks integration as simple as possible.

You can always manually validate the signature. The validation process works as follows:

1. Retrieve the key id from the X-GCS-KeyId header.
2. From your own configuration: retrieve the webhooks secret key belonging to that webhooks key id.
3. Retrieve the body of the request and convert it to bytes using UTF-8 encoding.
4. Create an HMAC-SHA256 signature of the resulting byte array and the webhooks secret key.
5. Encode the created signature using base64.
6. Retrieve the signature we created from the request's X-GCS-Signature HTTP header and verify it is the same as the base64 encoded signature you just created.
7. Below is an example in Java.

String signature = getHeaderValue(requestHeaders, "X-GCS-Signature");
String keyId = getHeaderValue(requestHeaders, "X-GCS-KeyId");
String secretKey = secretKeyStore.getSecretKey(keyId);
 
Mac hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec key = new SecretKeySpec(secretKey.getBytes(CHARSET), "HmacSHA256");
hmac.init(key);
 
byte[] unencodedResult = hmac.doFinal(body);
String expectedSignature = Base64.encodeBase64String(unencodedResult);
 
boolean isValid = areEqualSignatures(signature, expectedSignature);

You can of course also copy the validation code from the SDKs. The table below contains links to the SDK files in Github that contain the relevant code.

Changing the webhooks key needs to be done carefully because otherwise the events that are sent to you may be signed with a key that you do not have configured yet. It's best to follow these steps:

1. Create a second key in the configuration center. Webhooks will still sign all events with old one.
2. Now add the new key to your server configuration. Do not override the old one, just add it.
3. Now delete the old key in our configuration center. From that moment we will sign the messages with the new key
4. For a couple of minutes the incoming messages can be signed with either the new or the old key depending on if they were signed before or after the deletion of the old key. It's important that your code uses the X-GCS-KeyId to determine which key should be used for validating. If you are using the eCommerce plugins this will be done automatically as long as you configure the plugin with both the old and the new webhooks key. Keep in mind that messages that are in our retry queue will be signed with the new key at the moment they are sent again.
5. After an hour you can safely remove the old key from the plugin config so the only key that is still configured is the new one. 

It can take up to 10 minutes for webhooks to have picked up changes you made using the configuration center. Both for webhooks key changes and for endpoint changes, including activating or deactivating endpoints.

No, we do not allow HTTP endpoints, because the message body can contain privacy sensitive information. HTTPS endpoint should listen on the default port (443), non default ports are not supported.

No, all endpoints need to be unique within one merchant, even without taking the subscribed events into account. We do this to prevent merchants from mistakenly adding two identical endpoints. As an easy fix you can add dummy query parameters to one of the endpoint's URL so they become different.

We will stop sending messages to that endpoint. It can take up to 10 minutes for webhooks to have picked up this change.

In some setups two or more accounts manage the same merchant. If one of those accounts triggers an event then all subscribed endpoints of all accounts that manage that merchant will receive a webhooks messages. The message is signed with the webhooks key of the account the endpoint belong to, so you will be able to verify the signature. The message itself does not show which account triggered the event, if any. If your integration makes use of this setup make sure to handle this scenario. 

No, you can only see endpoints that were created by users of your own account. 

Yes, you can use the same endpoint since the merchant id is part of the message body.This makes it possible for your single endpoint to figure out for which merchant the message is meant. However: you will have to add that endpoint to each merchant separately in the configuration center. 

You should at least use the version of the server SDKs listed in the table below. Since the client SDKs don't handle any webhooks messages they do not feature are webhooks functionality.

No, this can not be prevented in all cases. You should make sure you can handle these situations. Since all events have a unique id you can protect against this by verifying that an event's id has not already been handled earlier. Since the unique id is part of the message body and thus also included in the messages signature this check will also guard against replay attacks.

Here are some examples of when we'll send an event twice:

1. Your endpoint did receive the message but the request timed out before you could send a proper response. We have no choice but to conclude that the delivery failed so we will retry sending the message at a later time. From your perspective this would look like us sending the same event twice.
2. Your endpoint did receive the message but did not send back an HTTP status code in the 2xx range. We will also retry in such a case.
3. The webhooks system experienced some issues and, for some event, wasn't able to reliably determine if they had already been delivered. These events will be send again to make sure that the endpoints received them at least once.

We do not limit the number of messages we send to an endpoint. So if you create one endpoint and subscribe it to all events it will be sent all these events shortly after they occur. 

CSRF tokens are a security measure that websites use to prevent cross-site request forgery attacks. Although this is a very important feature of the framework it will also prevent your server from successfully handling incoming webhooks requests. You will have to add an exception for the webhooks endpoints for webhooks to work properly.