Guides
API Reference

Our reference library for integrating with our API

FAQ

Find answers to our most frequently asked questions

Classic Docs

Documentation for our Classic API

Webhook management

You can manage webhooks in the business channel settings section of the Hub or by using our API.

Use this page to learn how to manage webhooks using our API.

Find out how to:

Return all webhooks 

Use this API request to view all your previously configured webhooks.

The GET request

Endpoints

GEThttps://api.checkout.com/webhooks
GEThttps://api.sandbox.checkout.com/webhooks

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

The GET response

Response example

[
  {
    "id": "wh_387ac7a83a054e37ae140105429d76b5",
    "url": "https://example.com/webhooks",
    "active": true,
    "headers": {
      "authorization": "1234"
    },
    "content_type": "json",
    "event_types": [
      "payment_approved",
      "payment_flagged",
      "payment_pending",
      "payment_declined",
      "payment_expired",
      "payment_canceled",
      "payment_voided",
      "payment_void_declined",
      "payment_captured",
      "payment_capture_declined",
      "payment_capture_pending",
      "payment_refunded",
      "payment_refund_declined",
      "payment_refund_pending",
      "payment_chargeback",
      "payment_retrieval",
      "payment_paid"
    ],
    "_links": {
      "self": {
        "href": "https://api.checkout.com/webhooks/wh_387ac7a83a054e37ae140105429d76b5"
      }
    }
  }
]

Other possible responses:

  • 204 - No webhooks have been configured
  • 500 - Unexpected server error

Add a new webhook 

Use this API request to add a new webhook. 

The POST request

Use the details below to set up your request.

Endpoints

https://api.checkout.com/webhooks
https://api.sandbox.checkout.com/webhooks

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Body parameters

Field nameDescription

url

REQUIRED

STRING
Your webhook endpoint.

active

OPTIONAL

BOOLEAN

Whether the webhook is active.
By default this is set to true.

content_type

OPTIONAL

BOOLEAN

The content type to be sent to the webhook endpoint.

By default this is set to json.

event_types

REQUIRED

ARRAY

The event types you want to subscribe to.

View a list of all available event types.

Request example

{
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ]
}

The POST response

Below is an example successful response with the details of the additional webhook.

Response example

{
  "id": "wh_387ac7a83a054e37ae140105429d76b5",
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ],
  "_links": {
    "self": {
      "href": "https://api.checkout.com/webhooks/wh_387ac7a83a054e37ae140105429d76b5"
    }
  }
}

Other possible responses:

  • 400 - Invalid request
  • 409 - Conflict. A webhook with the same URL is already configured
  • 500 - Unexpected server error

Return a single webhook 

Use this API request to view a single webhook using its webhook ID.

The GET request

Use the details below to set up your request.

Endpoints

GEThttps://api.checkout.com/webhooks/{webhook_id}
GEThttps://api.sandbox.checkout.com/webhooks/{webhook_id}

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Path parameters

PathValue

webhook_id

REQUIRED

The ID of the webhook you are requesting.

The GET response

Below is an example successful response where the details of the configured webhook are visible.

Response example

{
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ]
}

Other possible responses:

  • 404 - A webhook with the requested webhook_id was not found
  • 500 - Unexpected server error

Update a webhook 


Use this API request to update a single webhook using its webhook ID.

The PUT request

Use the details below to set up your request.

Endpoints

PUThttps://api.checkout.com/webhooks/{webhook_id}
PUThttps://api.sandbox.checkout.com/webhooks/{webhook_id}

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json


Path parameters

PathValue

webhook_id

REQUIRED

The ID of the webhook you are requesting.

Request example

{
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ]
}

The PUT response

Below is an example of a successful response where the details of the configured webhook are visible.

Response example

{
  "id": "wh_387ac7a83a054e37ae140105429d76b5",
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ],
  "_links": {
    "self": {
      "href": "https://api.checkout.com/webhooks/wh_387ac7a83a054e37ae140105429d76b5"
    }
  }
}

Other possible responses:

  • 400 - Invalid request
  • 404 - A webhook with the requested webhook_id was not found
  • 409 - Conflict. A webhook with the same URL is already configured
  • 500 - Unexpected server error

Partially update a webhook 


Use this API request to partially update a single webhook using its webhook ID.

You can update the following attributes:

  • webhook URL
  • webhook status (enabled or disabled)
  • content type
  • event type
  • headers

The PATCH request

Use the details below to set up your request.

Endpoints

PATCHhttps://api.checkout.com/webhooks/{webhook_id}
PATCHhttps://api.sandbox.checkout.com/webhooks/{webhook_id}

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Path parameters

PathValue

webhook_id

REQUIRED

The ID of the webhook you are partially updating.

Request examples

{
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ]
}
{
  "url": "https://example.com/webhooks",
  "active": true,
}
{
  "url": "https://example.com/webhooks",
  "active": false,
}

The PATCH response

Below is an example of a successful response where the details of the configured webhook are visible.

Response example

{
  "id": "wh_387ac7a83a054e37ae140105429d76b5",
  "url": "https://example.com/webhooks",
  "active": true,
  "headers": {
    "authorization": "1234"
  },
  "content_type": "json",
  "event_types": [
    "payment_approved",
    "payment_flagged",
    "payment_pending",
    "payment_declined",
    "payment_expired",
    "payment_canceled",
    "payment_voided",
    "payment_void_declined",
    "payment_captured",
    "payment_capture_declined",
    "payment_capture_pending",
    "payment_refunded",
    "payment_refund_declined",
    "payment_refund_pending",
    "payment_chargeback",
    "payment_retrieval"
  ],
  "_links": {
    "self": {
      "href": "https://api.checkout.com/webhooks/wh_387ac7a83a054e37ae140105429d76b5"
    }
  }
}

Other possible responses:

  • 404 - A webhook with the requested webhook_id was not found
  • 409 - Conflict. A webhook with the same URL is already configured

Delete a webhook 

Use this API request to delete a single webhook using its webhook ID.

The DELETE request

Use the details below to set up your request.

Endpoints

DELETEhttps://api.checkout.com/webhooks/{webhook_id}
DELETEhttps://api.sandbox.checkout.com/webhooks/{webhook_id}

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Path parameters

PathValue

webhook_id

REQUIRED

The ID of the webhook you are requesting to delete.

The DELETE response

A 200 response signals that the webhook was successfully deleted.

Other possible response: 404 - No webhook was found that matched the webhook ID.

Test a webhook 

Use this API request to test your webhook's integration without having to create any charges.

In order to use this API, you will need to add a webhook, if you haven't already. You do not need to be subscribed to any events.

The POST request

Use the details below to set up your request.

Endpoints

https://api.checkout.com/webhooks/{webhook_id}/test
https://api.sandbox.checkout.com/webhooks/{webhook_id}/test

Header parameters

HeaderValue

Authorization

REQUIRED

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type

REQUIRED

application/json

Path parameters

PathValue

webhook_id

REQUIRED

The ID of the webhook you are testing.

Body parameters

Field nameDescription

event-types

REQUIRED

ARRAY

An array of all the event types you want to test.

View a list of all possible event types.

Request example

{
  "event_types": [
    "payment_approved",
    "payment_captured"
  ]
}

The POST response

If you receive a 204 response, then your request was successful.

Other possible response: 404 - Webhook doesn't exist.