Webhooks
Last updated: August 10, 2022
When an event occurs, we send you a webhook notification to tell you what's happened so you can take action and keep your business running smoothly.
Webhooks provide a definitive confirmation of a status update and are used for a variety of purposes, such as fulfilling orders, sending automated status updates to customers, or even integrating with third-party application services.
Here are some of our webhooks' best features:
- View a filterable log of all your notifications
- Our webhook retry mechanism for failed webhooks
- Explanations and reasons why a notification failed
- View webhooks for chargebacks and retrievals
In the diagram below, a merchant using Frames has configured a payment_captured webhook to trigger a notification to the merchant's server confirming the payment.
Information
We highly recommend that you use payment_captured as the webhook trigger since this is the final state of a processed charge.
Set up your webhooks in the business channel settings section of the hub or by using our webhook management API.
Easily configure multiple webhook endpoints to perform various processes for each of your channels:
- add or remove webhook endpoints
- enable or disable a particular endpoint
- subscribe or unsubscribe your endpoint event types
- add authorization headers to your endpoints
Note
To receive webhook notifications, your server should acknowledge each one with a 2xx HTTP status code within 10 seconds. If we don't get this response in time, the webhook will fail and we will try to resend it.
When a webhook notification fails, the retry mechanism automatically tries to resend it multiple times. The best-effort retries are set to happen after 5, 10, 15, 30, 60, 240, and 720 minutes (in sandbox: 5, 10, 15, 30, and 60 minutes).
You can re-enable, view and configure the webhook at any time in the business level settings of the Hub. However, if you no longer require this particular event type, no further action is necessary.
Information
Amazon’s Simple Queue Service (SQS) features "at-least-once delivery"; this indicates that an endpoint could receive a webhook more than once if we receive duplicate copies of a message. Although this is a rare occurrence, we recommend that endpoints process webhooks in a manner that anticipates duplicates and deals with them appropriately. To do this, save all original webhooks, and when a new webhook is received, disregard it if it already exists.
Because webhook notifications are asynchronous, we recommend implementing a fallback logic in case you experience any delivery delays that could affect your cardholders' journey.
The fallback logic should be applied when no authorization or capture webhooks have been received within ~15 seconds after they were expected to be received.
- Call the GET payment details endpoint using the payment ID obtained in the authorization response. You can find instructions on how to do this here.
- Check the
statusfield in the response to find out the current status of the payment. For example,"status": "Captured".
Alternatively, you can use the GET payment actions endpoint to list all the different statuses the payment has been through so far.
A webhook signature is a security measure which allows you to verify the integrity and authenticity of the data you’re receiving. Each webhook contains a hash-based message authentication code (HMAC) in its CKO-Signature header. Checkout.com generates the HMAC by taking the contents of the webhook notification and hashing it using the secret key as the key.
What is an HMAC?
A hash-based message authentication code (HMAC) is a type of message authentication code involving a cryptographic hash function and a secret cryptographic key. If any change is made to the data being sent, the resulting HMAC will be completely different from the original. Additionally, since the key is known only to the sender and the receiver, no valid HMAC can be regenerated by anyone else.
Using signatures is simple. All you need to do is take the webhook's body and apply the SHA-256 hash function to it, using the secret key as the hash key. You then compare the resulting HMAC to the one contained in the CKO-Signature header. If the HMACs are identical, then the data corresponds to what Checkout.com sent. If they are different, this indicates that the data has been intercepted and altered in some way. You can simply delete the webhook notification and then regenerate it using our webhook management API.
If a client is configured to receive webhook notifications, callbacks will be sent from specific IP addresses depending on whether you're working in a sandbox or production (live) environment.
In general, we don't recommend restricting traffic to a set number of individual IP addresses but if you do, you’ll need to add the following IP addresses to your permission lists:
34.246.107.17552.31.105.5652.209.35.13052.210.86.14252.210.98.18554.246.243.142