Set up your webhook receiver

Last updated: November 20, 2024

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, using hash-based message authentication code (HMAC).

HMAC is a message encryption technique which makes use of 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.

As the cryptographic key is only known to the sender and receiver, any changes to the original data made by external actors will result in a different HMAC and invalidate the integrity of the data.

We generate the HMAC by hashing the contents of the webhook notification using the key you provide in your workflow's webhook action, and then send it in the hex-encoded (Base16) Cko-Signature header.

To validate that the message you received was sent by Checkout.com:

Hash the contents in the webhook body with the SHA-256 hash function, using your webhook's signature key as the hash key.
Compare the resulting HMAC with the one received in the Cko-Signature header.

If the HMACs are identical, the data corresponds to what we sent. If the HMACs are different, this indicates that the data has been intercepted and altered.

To avoid signature verification inconsistencies, we recommend that you perform the signature calculation based on the raw body from the HTTP request.

Information

If you calculate the signature based on a payload that has been deserialized and serialized again, this could change the precision of some values. This is particularly important for payloads which contain special characters. For example, ©, ®, or ™.

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.

If your webhook fails – for example, due to a network issue or a failure to acknowledge the webhook – we automatically retry the webhook.

We retry a webhook up to eight times at the following intervals after each previous attempt:

5 minutes
10 minutes
15 minutes
30 minutes
1 hour
4 hours
12 hours
12 hours

Once an attempt succeeds, future automatic retries are cancelled.

If all automatic attempts fail, we cancel the webhook. To replay the event, call the Reflow by event endpoint with the event's ID, or manually retry the webhook using the Dashboard.

Webhook events are guaranteed to be sent at least once, but the order in which the events are sent may vary.

This means that you may receive notifications in an unexpected order.

For this reason, we recommend that you design your implementation in a way that does not rely on the order that events are received in and handles delivery accordingly.

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.

For the full API specification, see the API reference.

post

https://api.checkout.com/workflows


1{
2  "name": "My Webhook Workflow",
3  "conditions": [
4    {
5      "type": "event",
6      "events": {
7        "gateway": [
8          "payment_approved",
9          "payment_declined",
10          "card_verification_declined",
11          "card_verified",
12          "payment_authorization_incremented",
13          "payment_authorization_increment_declined",
14          "payment_capture_declined",
15          "payment_captured",
16          "payment_refund_declined",
17          "payment_refunded",
18          "payment_void_declined",
19          "payment_voided"
20        ],
21        "dispute": [
22          "dispute_canceled",
23          "dispute_evidence_required",
24          "dispute_expired",
25          "dispute_lost",
26          "dispute_resolved",
27          "dispute_won"
28        ]
29      }
30    },
31    {
32      "type": "entity",
33      "entities": ["ent_xyfdshfudosfdshfdiosfds", "ent_fidjosfjdisofdjsifdosfu"]
34    }
35  ],
36  "actions": [
37    {
38      "type": "webhook",
39      "url": "https://example.com/webhook-receiver",
40      "headers": {
41        "Authorization": "secret-key"
42      },
43      "signature": {
44        "key": "signature-key"
45      }
46    }
47  ]
48}


1{
2  "id": "wf_wlu3wxc26jounofs5iez75qaqa",
3  "_links": {
4    "self": {
5      "href": "https://api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa"
6    }
7  }
8}

Note

Your webhook receiver must acknowledge every webhook it receives within 10 seconds. If it does not, the webhook times out and fails.

Set up your webhook receiver

Webhook signatures

Information

HTTP headers

Automatic retries

Webhook event sequencing

IP address allowlisting

Create a workflow

Endpoints

Request example

Response example

Note