You're viewing our new Unified Payments API documentation. Click here to access our Classic API docs.

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 request

Use the details below to set up your request.

Endpoints

Live

GEThttps://api.checkout.com/webhooks

Sandbox

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

Header parameters

Header
Value

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 response

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

[
  {
    "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_cancelled",
      "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

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

Add a new webhook

Use this API request to add a new webhook.

The request

Use the details below to set up your request.

Endpoints

Live

https://api.checkout.com/webhooks

Sandbox

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

Header parameters

Header
Value

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 name
Description

url
String
Required

Your webhook endpoint.

active
Boolean
Optional

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

content_type
Boolean
Optional

The content type to be sent to the webhook endpoint.

By default this is set to json.

event_types
Array
Required

The event types you want to subscribe to.

You can view a list of all available event types here.

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_cancelled",
    "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 response

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

{
  "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_cancelled",
    "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 request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

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
Value

webhook_id
Required

The ID of the webhook you are requesting.

The response

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

{
  "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_cancelled",
    "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 request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

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
Value

webhook_id
Required

The ID of the webhook you are updating.

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_cancelled",
    "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 response

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

{
  "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_cancelled",
    "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 (Enable/Disable)
  • Content type
  • Event type
  • Headers

The request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

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
Value

webhook_id
Required

The ID of the webhook you are partially updating.

Request example

Attributes can be added and deleted depending on your update needs. Use the tabs to view a request to re-enable or disable your webhook only.

{
  "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_cancelled",
    "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 response

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

{
  "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_cancelled",
    "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 request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

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
Value

webhook_id
Required

The ID of the webhook you are requesting to delete.

The response

A 200 response signals that the webhook was successfully deleted.

Other possible responses:

  • 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 request

Use the details below to set up your request.

Endpoints

Live

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

Sandbox

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

Header and path parameters

Header
Value

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
Value

webhook_id
Required

The ID of the webhook you are testing.

Body parameters

Field name
Description

event-types
Array
Required

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

Click here to view a list of all possible event types.

Example request

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

The response

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

Other possible responses:

  • 404 - Webhook doesn't exist

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.


Webhook management


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.