Manage webhooks

Learn how to manage your webhook workflows using our API.

Find out how to:

Use this API request to add a new workflow.

For the full API specification, see the API reference.

post

https://api.checkout.com/workflows


1{
2  "name": "Webhooks workflow",
3  "active": true,
4  "conditions": [
5    {
6      "type": "event",
7      "events": {
8        "gateway": [
9          "payment_approved",
10          "payment_declined",
11          "card_verification_declined",
12          "card_verified",
13          "payment_authorization_incremented",
14          "payment_authorization_increment_declined",
15          "payment_capture_declined",
16          "payment_captured",
17          "payment_refund_declined",
18          "payment_refunded",
19          "payment_void_declined",
20          "payment_voided"
21        ],
22        "dispute": [
23          "dispute_canceled",
24          "dispute_evidence_required",
25          "dispute_expired",
26          "dispute_lost",
27          "dispute_resolved",
28          "dispute_won"
29        ]
30      }
31    },
32    {
33      "type": "entity",
34      "entities": ["ent_xyfdshfudosfdshfdiosfds", "ent_fidjosfjdisofdjsifdosfu"]
35    },
36    {
37      "type": "processing_channel",
38      "processing_channels": ["pc_axclravnqf5u5ejkweijnp5zc4"]
39    }
40  ],
41  "actions": [
42    {
43      "type": "webhook",
44      "url": "https://example.com/webhooks",
45      "headers": {
46        "Authorization": "<AUTHORIZATION_UUID>"
47      },
48      "signature": {
49        "method": "HMACSHA256",
50        "key": "8V8x0dLK%AyD*DNS8JJr"
51      }
52    }
53  ]
54}

The following example shows a successful response with the details of the additional workflow:


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

Other possible responses:

401 - Unauthorized
422 - Invalid data was sent
500 - Internal error

Before setting up a workflow in production, you can test the workflow configuration in sandbox. If the test workflow is valid, the actions for all included event types will be triggered.

For the full API specification, see the API reference.

post

https://api.sandbox.checkout.com/workflows/{workflowId}/test


1{
2  "event_types": [
3    "payment_approved",
4    "payment_declined",
5    "card_verification_declined",
6    "card_verified",
7    "payment_captured",
8    "payment_refunded",
9    "payment_voided",
10    "dispute_canceled",
11    "dispute_evidence_required",
12    "dispute_expired",
13    "dispute_lost",
14    "dispute_resolved",
15    "dispute_won"
16  ]
17}

A 204 response signals that the test workflow was successfully triggered.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
422 - Invalid data was sent
500 - Internal error

Use this API request to delete an existing workflow. The actions of already executed workflows will be still processed.

For the full API specification, see the API reference.

delete

https://api.checkout.com/workflows/{workflowId}

A 204 response signals that the workflow was successfully deleted.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
500 - Internal error

Use this API request to view the details of a single workflow using its workflow ID.

Use the details below to set up your request.

For the full API specification, see the API reference.

get

https://api.checkout.com/workflows/{workflowId}

The following example shows a successful response where the details of the configured workflow are visible:


1{
2  "id": "<WORKFLOW_ID>",
3  "name": "Single workflow example",
4  "active": true,
5  "conditions": [
6    {
7      "id": "<WORKFLOW_CONDITION_ID>",
8      "type": "event",
9      "events": {
10        "gwc_notifier1": ["payment_approved"]
11      }
12    },
13    {
14      "id": "<WORKFLOW_CONDITION_ID>",
15      "type": "entity",
16      "entities": ["<ENTITY_ID>"]
17    },
18    {
19      "id": "<WORKFLOW_CONDITION_ID>",
20      "type": "processing_channel",
21      "processing_channels": ["<PROCESSING_CHANNEL_ID>"]
22    }
23  ],
24  "actions": [
25    {
26      "id": "<WORKFLOW_ACTION_ID>",
27      "type": "webhook",
28      "url": "https://devapi.ckotech.co/webhooktester/webhooks/testPC_good_test2",
29      "headers": {
30        "Authorization": "secr"
31      },
32      "signature": {
33        "method": "HMACSHA256",
34        "key": "signa"
35      }
36    }
37  ],
38  "_links": {
39    "self": {
40      "href": "https://flow.cko-qa.ckotech.co/workflows/<WORKFLOW_ID>"
41    }
42  }
43}

Other possible responses:

401 - Unauthorized
404 - Workflow not Found
500 - Internal error

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

For the full API specification, see the API reference.

get

https://api.checkout.com/workflows


1{
2  "data": [
3    {
4      "id": "wf_wlu3wxc26jounofs5iez75qaqa",
5      "name": "Webhooks workflow",
6      "active": true,
7      "_links": {
8        "self": {
9          "href": "https://api.checkout.com/workflows/wf_wlu3wxc26jounofs5iez75qaqa"
10        }
11      }
12    }
13  ]
14}

Other possible responses:

401 - Unauthorized
500 - Internal error

To update a previously created workflow, use the following endpoint, passing the workflow's ID in the path, and the new properties for the workflow in the request body.

For the full API specification, see the API reference.

patch

https://api.checkout.com/workflows/{workflowId}


1{
2  "name": "Webhooks workflow",
3  "active": true,
4  "conditions": [
5    {
6      "type": "event",
7      "events": {
8        "gateway": [
9          "payment_approved",
10          "payment_pending",
11          "payment_declined"
12        ]
13      }
14    },
15    {
16      "type": "entity",
17      "entities": [
18        "ent_xyfdshfudosfdshfdiosfds",
19        "ent_fidjosfjdisofdjsifdosfu"
20      ]
21    },
22    {
23      "type": "processing_channel",
24      "processing_channels": [
25        "pc_axclravnqf5u5ejkweijnp5zc4"
26      ]
27    }
28  ],
29  "actions": [
30    {
31      "workflow_action_id": "wfa_itja4x7zgzye3andzqq62u4hvq",
32      "type": "webhook",
33      "url": "https://example.com/webhooks",
34      "headers": {
35        "Authorization": "<AUTHORIZATION_UUID>"
36      },
37      "signature": {
38        "method": "HMACSHA256",
39        "key": "8V8x0dLK%AyD*DNS8JJr"
40      }
41    }
42  ]
43}

The following example shows a successful response with the details of the additional workflow:


1{
2  "id": "wf_c7svxlvo2bbuva4f6s3xu4f7wm",
3  "name": "Webhooks workflow",
4  "active": true,
5  "conditions": [
6    {
7      "id": "wfc_tisekcawefze3l27uaai6hz74e",
8      "type": "event",
9      "events": {
10        "gateway": [
11          "payment_approved",
12          "payment_pending",
13          "payment_declined"
14        ]
15      }
16    },
17    {
18      "id": "wfc_tisekcawefze3l27uaai6hz74y",
19      "type": "entity",
20      "entities": [
21        "ent_xyfdshfudosfdshfdiosfds",
22        "ent_fidjosfjdisofdjsifdosfu"
23      ]
24    },
25    {
26      "id": "wfc_tisekcawefze3l27uaai6hz26y",
27      "type": "processing_channel",
28      "processing_channels": [
29        "pc_axclravnqf5u5ejkweijnp5zc4"
30      ]
31    }
32  ],
33  "actions": [
34    {
35      "id": "wfa_itja4x7zgzye3andzqq62u4hvq",
36      "type": "webhook",
37      "url": "https://example.com/webhooks",
38      "headers": {
39        "Authorization": "<AUTHORIZATION_UUID>"
40      },
41      "signature": {
42        "method": "HMACSHA256",
43        "key": "8V8x0dLK%AyD*DNS8JJr"
44      }
45    }
46  ],
47  "_links": {
48    "self": {
49      "href": "http://flow.cko.lon/client/workflows/wf_c7svxlvo2bbuva4f6s3xu4f7wm"
50    }
51  }
52}

401 - Unauthorized
404 - Workflow not found
422 - Invalid data was sent
500 - Internal error

To update the actions of a workflow, use the following endpoint, passing the workflow's ID and action ID in the path, and the details you want to update in the request body.

For the full API specification, see the API reference.

put

https://api.checkout.com/workflows/{workflowId}/actions/{workflowActionId}


1{
2  "type": "webhook",
3  "url": "https://example.com/webhooks/checkout",
4  "headers": {
5    "Authorization": "<AUTHORIZATION_UUID>"
6  },
7  "signature": {
8    "method": "HMACSHA256",
9    "key": "public-signing-key"
10  }
11}

If you receive a 200 success response, the workflow action was successfully updated.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow action not found
422 - Invalid data was sent
500 - Internal error

To update the conditions of a workflow, use the following endpoint, passing the workflow's ID and condition ID in the path, and the details you want to update in the request body.

For the full API specification, see the API reference.

put

https://api.checkout.com/workflows/{workflowId}/conditions/{workflowConditionId}


1{
2  "type": "event",
3  "events": {
4    "gateway": [
5      "card_verified",
6      "card_verification_declined",
7      "payment_approved",
8      "payment_pending",
9      "payment_declined",
10      "payment_voided",
11      "payment_captured",
12      "payment_refunded"
13    ],
14    "dispute": [
15      "dispute_canceled",
16      "dispute_evidence_required",
17      "dispute_expired",
18      "dispute_lost",
19      "dispute_resolved",
20      "dispute_won"
21    ]
22  }
23}

If you receive a 200 success response, the workflow condition was successfully updated.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow condition not found
422 - Invalid data was sent
500 - Internal error

Use this API request to add an action to an existing workflow.

For the full API specification, see the API reference.

post

https://api.checkout.com/workflows/{workflowId}/actions


1{
2  "type": "webhook",
3  "url": "https://example.com/webhooks/checkout",
4  "headers": {
5    "Authorization": "<AUTHORIZATION_UUID>"
6  },
7  "signature": {
8    "method": "HMACSHA256",
9    "key": "public-signing-key"
10  }
11}

If you receive a 201 success response, the workflow action was successfully added.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
422 - Invalid data was sent
500 - Internal error

Use this API request to delete an action from an existing workflow.

For the full API specification, see the API reference.

delete

https://api.checkout.com/workflows/{workflowId}/actions/{workflowActionId}

A 204 response signals that the workflow action was successfully deleted.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow action not found
500 - Internal error

Use this API request to add a condition to an existing workflow.

For the full API specification, see the API reference.

post

https://api.checkout.com/workflows/{workflowId}/conditions


1{
2  "type": "event",
3  "events": {
4    "gateway": [
5      "card_verified",
6      "card_verification_declined",
7      "payment_approved",
8      "payment_pending",
9      "payment_declined",
10      "payment_voided",
11      "payment_captured",
12      "payment_refunded"
13    ],
14    "disputes": [
15      "dispute_canceled",
16      "dispute_evidence_required",
17      "dispute_expired",
18      "dispute_lost",
19      "dispute_resolved",
20      "dispute_won"
21    ]
22  }
23}

If you receive a 201 success response, the workflow condition was successfully added.

Other possible responses:

401 - Unauthorized
404 - Workflow not found
422 - Invalid data was sent
500 - Internal error

Use this API request to delete a condition from an existing workflow.

For the full API specification, see the API reference.

delete

https://api.checkout.com/workflows/{workflowId}/actions/{workflowConditionId}

A 204 response signals that the workflow condition was successfully deleted.

Other possible responses:

401 - Unauthorized
404 - Workflow or workflow action not found
500 - Internal error

Add a new workflow

Endpoints

Request example

Response example

Test a workflow

Endpoint

Request example

Response

Delete a workflow

Endpoints

Response

Return a single workflow

Endpoints

Response example

Return all workflows

Endpoints

Response example

Update a workflow

Endpoints

Request example

Response example

Update the actions of a workflow

Endpoints

Request example

Response

Update the conditions of a workflow

Endpoints

Request example

Response

Add a workflow action

Endpoints

Request example

Response

Delete a workflow action

Endpoints

Response

Add a workflow condition

Endpoints

Request example

Response

Delete a workflow condition

Endpoints

Response

Related topics

Set up your webhook receiver

View events

Retrigger events