Configure your webhook server

Last updated: November 12, 2025

You can configure your webhook server to receive notifications about various events related to your account. For example, payment lifecycle activity, changes to balances, or progress on disputes.

Configure your sever to handle retries and sequencing.
Allow Checkout.com IP addresses, if required.
Provide the URL you want Checkout.com to send webhooks to using either the Dashboard or the API. You can also build a workflow, with specific actions and conditions, to meet your business needs.
Optionally, authenticate each webhook when you receive it on your server using HTTP headers.
Validate that the payload was sent by Checkout.com.
Acknowledge the webhook.

Configure your server to handle automatic retries.

Checkout.com guarantees to send webhooks at least once, but the sequence in which we send them may vary. This means that you may receive webhooks in an unexpected order.

We therefore recommend that your webhook server does not rely on the order of webhooks and handles delivery accordingly.

In general, Checkout.com does not recommend restricting traffic to a set number of individual IP addresses. If you do so, you must add our IP addresses to your allowlists.

Information

For a list of our IP addresses, see IP addresses.

To provide your webhook URL and create a configuration in the Dashboard, you must have one of the following user roles:

Admin
Compliance operator
Developer
A custom role with the following permissions:
- Create, edit and delete workflow notifications
- View secret keys
- View the list of workflow notifications

For each configuration, you can subscribe to an unlimited number of event types.

Sign in to the Dashboard.
Select the Developers icon in the top navigation bar and open the Webhooks tab.
Select Create configuration.
Enter a Name for the webhook configuration.
Enter the Endpoint URL you want Checkout.com to send webhooks to, prefixed with either https:// or http://.
To generate an authorization header key to include in your webhook headers to validate that Checkout.com sent the webhook, select Generate key.
To generate a signature key to hash the webhook payload as an HMAC, select Generate key.
Optionally, enter an HTTP header Key and Value to pass additional information with webhooks, and select Add new header.
Select the checkboxes for event types you want to subscribe to.
Select the entities or processing channels you want to receive webhooks for.
Select Create webhook to complete your configuration.

Checkout.com starts sending the webhooks to which you subscribed to the specified URL immediately.

Call the Add a workflow endpoint.

In the request body, specify the webhook events you want to subscribe to and any actions and conditions.

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}

You can provide a key in the Authorization HTTP header of every webhook you receive to authenticate it on your server.

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

Hash the payload with the SHA-256 hash function, using your webhook 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 payload corresponds to what we sent. If the HMACs are different, this indicates that the payload was intercepted and altered.

To avoid signature verification inconsistencies, perform the signature calculation based on the raw payload 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 that contain special characters. For example, ©, ®, or ™.

Your webhook server must acknowledge every webhook it receives within 10 seconds.

Information

If you do not acknowledge a webhook within the time limit, it times out and fails.

Configure your webhook server

How it works

Handle retries and sequencing

Allow Checkout.com IP addresses

Information

Create a webhook configuration in the Dashboard

Add a webhook workflow using the API

Request example

Response example

Authenticate the webhook

Validate the payload

Information

Acknowledge the webhook

Information