Manage workflows

Learn how to manage your workflows using our API.

Find out how to:

• Add a new workflow
• Test a workflow
• Delete a workflow
• Return a single workflow
• Return all workflows
• Update the name of a workflow
• Update the actions of a workflow
• Update the conditions of a workflow
• Add a workflow action
• Delete a workflow action
• Add a workflow condition
• Delete a workflow condition

Use this API request to add a new workflow.

For the full API specification, see the API reference.

json
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": [
35        "ent_xyfdshfudosfdshfdiosfds",
36        "ent_fidjosfjdisofdjsifdosfu"
37      ]
38    },
39    {
40      "type": "processing_channel",
41      "processing_channels": [
42        "pc_axclravnqf5u5ejkweijnp5zc4"
43      ]
44    }
45  ],
46  "actions": [
47    {
48      "type": "webhook",
49      "url": "https://example.com/webhooks",
50      "headers": {
51        "Authorization": "70ed20ff-ba31-4ea3-b3ef-772f2be1cbdf"
52      },
53      "signature": {
54        "method": "HMACSHA256",
55        "key": "8V8x0dLK%AyD*DNS8JJr"
56      }
57    }
58  ]
59}

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

json
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
• 404 - 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.

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

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.

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

json
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": [
11                    "payment_approved"
12                ]
13            }
14        },
15        {
16            "id": "<WORKFLOW_CONDITION_ID>",
17            "type": "entity",
18            "entities": [
19                "<ENTITY_ID>"
20            ]
21        },
22        {
23            "id": "<WORKFLOW_CONDITION_ID>",
24            "type": "processing_channel",
25            "processing_channels": [
26                "<PROCESSING_CHANNEL_ID>"
27            ]
28        }
29    ],
30    "actions": [
31        {
32            "id": "<WORKFLOW_ACTION_ID>",
33            "type": "webhook",
34            "url": "https://devapi.ckotech.co/webhooktester/webhooks/testPC_good_test2",
35            "headers": {
36                "Authorization": "secr******"
37            },
38            "signature": {
39                "method": "HMACSHA256",
40                "key": "signa********"
41            }
42        }
43    ],
44    "_links": {
45        "self": {
46            "href": "https://flow.cko-qa.ckotech.co/workflows/<WORKFLOW_ID>"
47        }
48    }
49}

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.

json
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

Use the following endpoint to update the name of a previously created workflow, passing the existing workflow's ID in the path and the new name for the workflow in the request body.

For the full API specification, see the API reference.

json
1{
2  "name": "Webhooks workflow",
3  "active": true
4}

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

json
1{
2  "name": "Webhooks workflow",
3  "active": true
4}

• 401 - Unauthorized
• 404 - Workflow not found
• 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.

json
1{
2  "type": "webhook",
3  "url": "https://example.com/webhooks/checkout",
4  "headers": {
5    "Authorization": "70ed20ff-ba31-4ea3-b3ef-772f2be1cbdf"
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.

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

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

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.

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

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