New Webhooks functionality has been added to the MyCashflow API, and it will replace the old Webhooks extension in October 2022. Here you can read more about differences between the new and old Webhooks implementations and how to enable the new Webhooks.

The new Webhooks API is different from the old implementation as follows:

  • No graphical user interface: All the functions need to be implemented in code in the integration.
  • Available starting from the Advanced plan: The Webhooks API is incorporated in the MyCashflow API.
  • A different data format: The new Webhooks API uses the JSON format instead of the old XML format.

See also the following materials:

Enabling the new Webhooks

The new Webhooks is enabled by sending a POST /api/v1/webhooks request to the Webhooks API of the relevant online store. This sets Webhooks to 1) follow a specified event (e.g., orders arriving) and 2) send a message about the event to a specific URL address.

As a result of the request, a Webhooks subscription is created in the online store, and the API returns the requested data in a response message.

In the example below, Webhooks is set to follow the creation of orders in the online store:

POST /api/v1/webhooks
{
  "topic": "order.created",
  "expands": [
    "payments",
    "shipments"
  ],
  "url": "https://www.example.com"
}

Following a successful request, the API will respond by sending a JSON object that contains the unique UUID identifier of the Webhooks subscription, as well as other data concerning the order.

Save the JSON object you have received in, e.g., a file or database within the integration.

The UUID identifier incorporated in the response message will be used to validate the Webhooks messages sent by the API, which is an important data security measure.

Below is an example of a response message to a successful Webhooks order:

{
    "data": {
        "uuid": "083c584d-ae65-11ec-aef4-0242ac130002",
        "user_id": 2,
        "topic": "order.created",
        "expands": [
            "payments",
            "shipments"
        ],
        "url": "https://www.example.com"
    }
}

Updating the Webhooks functions for the new API

The order processing functions available in the old Webhooks are not supported by the new API, and therefore the integrations that use them need to be updated to use corresponding functions available in the MyCashflow API as follows:

  • POST /webhooks/process?action=deliver: Marks the order as shipped.
    Replacement function:
  • POST /webhooks/process?action=add_comment: Adds a comment to the order.

    Replacement function: You can add comments to orders with the POST /api/v0/orders/{orderId}/comments request.

  • GET /webhooks/get?order={orderId}: Fetches an individual order.

    Replacement function: You can fetch an individual order with the GET /api/v0/orders/{orderId} request.

  • GET /webhooks/changes?created_after_ts/update_after_ts: Fetches all orders created or updated after a specified point in time.
    Replacement function: You can fetch orders created or updated over a specified time span by using the following parameters of the order API:
    • /api/v0/orders?created_at-from={timestamp}
    • /api/v0/orders?updated_at-from={timestamp}
  • GET /webhooks/changes?order_ids={orderIds}: Fetches a list of orders based on ID numbers.

    Replacement function: There is no MyCashflow API function that allows you to fetch several orders with a single request based on ID numbers, but you can fetch orders one-by-one by using the GET /api/v0/orders/{orderId} request.

  • GET /webhooks/send: Re-sends a Webhook message (for example, if it failed earlier).

    Replacement function: There is no dedicated function to re-send a Webhook message in the new Webhooks implementation, but if a transmission fails, the new Webhooks will automatically try to re-send the message 15 times: the first time after 15 seconds and then again after twice the time (the interval is redoubled after each attempt).