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
Add a new webhook
Return a single webhook
Update a webhook
Partially update a webhook
Delete a webhook
Test a webhook

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

Use the details below to set up your request.

Endpoints

Live

POSThttps://api.checkout.com/webhooks

Sandbox

POSThttps://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. 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 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_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 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_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 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_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 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_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 (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_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 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_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 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

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

Sandbox

POSThttps://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. 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 [email protected].

Return all webhooks

The request

Endpoints

Live

Sandbox

Header parameters

The response

Add a new webhook

The request

Endpoints

Live

Sandbox

Header parameters

Body parameters

Request example

The response

Return a single webhook

The request

Endpoints

Live

Sandbox

Header and path parameters

The response

Update a webhook

The request

Endpoints

Live

Sandbox

Header and path parameters

Request example

The response

Partially update a webhook

The request

Endpoints

Live

Sandbox

Header and path parameters

Request example

The response

Delete a webhook

The request

Endpoints

Live

Sandbox

Header and path parameters

The response

Test a webhook

📘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

Endpoints

Live

Sandbox

Header and path parameters

Body parameters

Example request

The response

Can we help?

📘
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.