You're viewing documentation for our latest API. This will not impact your integration, but you will need the documentation relevant to you. If you have an account with Checkout.com you have received an email confirming which version to use.
To start receiving webhook notifications, you can use our Workflows API to create a workflow by specifying both the events you would like to subscribe to and the necessary configurations for the webhook workflow action.
The webhook workflow action supports the following features:
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. We generate the HMAC by taking the contents of the webhook notification and hashing it using the key provided in the webhook action of your workflow.
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 your 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 we sent. If they are different, this indicates that the data has been intercepted and altered in some way.
You can configure HTTP headers which will be included in each webhook notification. You can use this feature to configure a key that you want to provide in the Authorization HTTP header of your webhook notifications, allowing you to authenticate the request with your server.
When a webhook notification fails, the retry mechanism begins. We automatically try to resend the webhook notification multiple times, following a schedule. Each retry happens after the specified times:
12 hours (twice)
After the final failure, we will cancel the webhook notification. If you need to replay the events, you can use the Events API.
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 our IP addresses to your permission lists. The current IP address list can be found on the IP address page.