Receive webhooks
Webhooks are automated messages that Checkout.com sends your server when events related to your account occur. For example, payment lifecycle activity, changes to balances, or progress on disputes.
You must first configure your webhook server. You can then build webhook flows tailored to your business needs using the Dashboard or the API.
A webhook signature is a security measure that enables you to verify the integrity and authenticity of the data you receive in the webhook payload. It uses a hash-based message authentication code (HMAC).
HMAC is a message encryption technique that uses a hash function and a cryptographic key known only to the sender and receiver.
The sender calculates the hash value for the data using the key and uses the result to generate the HMAC. The sender then transmits the HMAC alongside the original data.
The receiver calculates the hash value for the original data received. If the calculated HMAC matches the HMAC received, the transmission is authenticated.
Because the cryptographic key is only known to the sender and receiver, any changes to the original data made by external actors result in a different HMAC and invalidate the data's integrity.
Checkout.com generates the HMAC by hashing the webhook payload using the key you provide in your workflow's webhook action, and then sends it in the hex-encoded (Base16) Cko-Signature header.
If a webhook fails – for example, due to a network issue or if you fail to acknowledge the webhook – Checkout.com automatically resends the webhook.
We resend webhooks up to eight times at the following intervals after each previous attempt:
- Five minutes
- 10 minutes
- 15 minutes
- 30 minutes
- One hour
- Four hours
- 12 hours
- 12 hours
When an attempt succeeds, future automatic retries are canceled. If all automatic attempts fail, we cancel the webhook.
You can resend webhooks using the Dashboard and the API.
Checkout.com guarantees to send webhooks at least once, but the order in which we send them may vary. This means that you may receive webhooks in an unexpected order.