Set up your webhook receiver

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.

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 custom 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:

After the final failure, we will cancel the webhook notification. If you need to replay the events, you can use the Events 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:

For the full API specification, see the API reference.

{
    "name": "My Webhook Workflow",
    "conditions": [{
            "type": "event",
            "events": {
                "gateway": [
                    "payment_approved",
                    "payment_declined",
                    "card_verification_declined",
                    "card_verified",
                    "payment_authorization_incremented",
                    "payment_authorization_increment_declined",
                    "payment_capture_declined",
                    "payment_captured",
                    "payment_refund_declined",
                    "payment_refunded",
                    "payment_void_declined",
                    "payment_voided"
                ],
                "dispute": [
                    "dispute_canceled",
                    "dispute_evidence_required",
                    "dispute_expired",
                    "dispute_lost",
                    "dispute_resolved",
                    "dispute_won"
                ]
            }
        },
        {
            "type": "entity",
            "entities": [
                "ent_xyfdshfudosfdshfdiosfds",
                "ent_fidjosfjdisofdjsifdosfu"
            ]
        }
    ],
    "actions": [{
        "type": "webhook",
        "url": "https://example.com/webhook-receiver",
        "headers": {
            "Authorization": "secret-key"
        },
        "signature": {
            "key": "signature-key"
        }
    }]
}

{
  "id": "wf_wlu3wxc26jounofs5iez75qaqa",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa"
    }
  }
}