Skip to content

Set up your webhook receiver

Last updated: July 06, 2022

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:

Webhook signatures

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.

What is HMAC?

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.

Custom headers

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.

Automatic retries

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:

  1. 5 minutes
  2. 10 minutes
  3. 15 minutes
  4. 30 minutes
  5. 1 hour
  6. 4 hours
  7. 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.

IP address whitelisting

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:

    • 34.246.107.175
    • 52.209.35.130
    • 54.246.243.142

    Creating a workflow

    Endpoints

    For the full API specification, see the API reference.

      post

      https://api.checkout.com/workflows

      Copied!

      Request example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      {
      "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"
      }
      }]
      }

      Response example

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