Skip to content

Manage workflows

Last updated: 10th August 2022

Learn how to manage your workflows using our API.

Find out how to:


Return all workflows

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

Endpoints

For the full API specification, see the API reference.

    get

    https://api.checkout.com/workflows

    Response example

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

    Other possible responses:

    • 401 - Unauthorized
    • 500 - Internal error

    Return a single workflow

    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.

    Endpoints

    For the full API specification, see the API reference.

      get

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

      Response example

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

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

      Other possible responses:

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

      Add a new workflow

      Use this API request to add a new workflow.

      Endpoints

      For the full API specification, see the API reference.

        post

        https://api.checkout.com/workflows

        Request example

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

        Response example

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

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

        Other possible responses:

        • 401 - Unauthorized
        • 404 - Invalid data was sent
        • 500 - Internal error

        Update the name of a workflow

        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.

        You can find the full specification in our API reference.

        Endpoints

        For the full API specification, see the API reference.

          patch

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

          Request example

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

          Response example

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

          1
          2
          3
          4
          {
          "name": "Webhooks workflow",
          "active": true
          }
          • 401 - Unauthorized
          • 404 - Workflow not found
          • 500 - Internal error

          Update the actions of a workflow

          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.

          You can find the full specification in our API reference.

          Endpoints

          For the full API specification, see the API reference.

            put

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

            Request example

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            {
            "type": "webhook",
            "url": "https://example.com/webhooks/checkout",
            "headers": {
            "Authorization": "70ed20ff-ba31-4ea3-b3ef-772f2be1cbdf"
            },
            "signature": {
            "method": "HMACSHA256",
            "key": "public-signing-key"
            }
            }

            Response

            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

            Update the conditions of a workflow

            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.

            You can find the full specification in our API reference.

            Endpoints

            For the full API specification, see the API reference.

              put

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

              Request example

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

              Response

              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

              Delete a workflow

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

              Endpoints

              For the full API specification, see the API reference.

                delete

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

                Response

                A 204 response signals that the workflow was successfully deleted.

                Other possible responses:

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

                Test a workflow

                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.

                Endpoint

                For the full API specification, see the API reference.

                  post

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

                  Request example

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

                  Response

                  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