Webhooks (deprecated)

A webhook is a method of data transfer that enables web developers to define custom HTTP callbacks that are triggered by certain events.

The Webhooks extension will be removed in October 2022

Existing applications implemented with Webhooks remain operational, but creating new ones is not recommended.

Available as a replacement, there is the new Webhooks API incorporated in the MyCashflow API.

Learn more about the migration to the new Webhooks.

Currently, MyCashflow's Webhooks extension enables you to:

Get order data
Processing orders
Add order comments

The extension can be used to integrate your online store's orders with external software. Integrations can also be implemented by using MyCashflow REST API.

Extensions are not available in MyCashflow Free plan.

Pricing

Using the extension is free of charge.

Basic principles

Webhooks are used by sending HTTP requests in a programming language (usually by using the cURL software) to the online store's Webhooks address. From the address, MyCashflow's Webhooks extension returns an answer to the request in XML format.

Webhooks commands of the GET type can also be used by entering the desired Webhooks address in the browser's address bar. In this way you can easily test Webhooks requests in your online store.

Whenever an order arrives at your online store, an automatic POST request is sent to the address defined in the extension settings (apart from orders created via MyCashflow API).

Below you can see descriptions of all parts of a Webhooks request:

The connecting point of all Webhooks requests is https://STOREADDRESS.mycashflow.fi/webhooks/
The desired action is then added after the connecting point (see the list of permitted actions): https://STOREADDRESS.mycashflow.fi/webhooks/get
Next the request is supplemented with the relevant GET or POST parameters: https://STOREADDRESS.mycashflow.fi/webhooks/get?order=n
At the end, the online store's individual API key is added to the request: https://STOREADDRESS.mycashflow.fi/webhooks/get?order=n&key=jyghji765rfghji
- When performing a Webhooks request in the browser's address bar, there is no need to add the API key to the address as long as you are logged in to your online store's admin panel.

The example below illustrates a Webhooks request in which a public order comment is sent to the customer:

https://STOREADDRESS.mycashflow.fi/webhooks/process
    action=add_comment
    order=23
    message="Public comment's contents"
    public_message=1
    key=kjhbnko987654e

Installation and setup

Extensions are not available in MyCashflow Free plan.

In the extension settings, define the address to which Webhooks callbacks should be sent from the online store as well as the API key used for authentication.

When a new order is placed in the online store, an automatic POST request with order details will be sent to the Webhooks address.

After defining the Webhooks settings, make sure that the extension works properly by sending a request to the address you've indicated (see the section below for permitted actions). For instance, you can place a test order so than an automatic order notification is sent.

Webhooks actions

You can see below all actions enabled by MyCashflow's Webhooks extension and their parameters.

See also the examples that illustrate how the actions can be used in practice.

For more information about the structure of the answer in XML format, see #concept_eyp_zpg_4db.


`POST /webhooks/processaction=deliver`
Marks the order as shipped.
`order`	Integers	Processed order ID
`send_email`	0 / 1	The value "1" sends shipping confirmation via email to the customer and shipping address. By default, no confirmation is sent (value 0).


`POST /webhooks/processaction=add_comment`
Adds a comment to the order.
`order`	Integers	Processed order ID
`public_message`	0 / 1	Defines whether a comment is public, and a comment notification should be sent via email to the customer and delivery address (a value of 1). Comments are private by default (value 0).
`message`	Text	The order comment's content in text format.


`GET /webhooks/get`
Used for fetching one or more orders based on their ID numbers.
`order`	Integers	ID number of the order to be fetched
`order_ids`	Integer table	Used for fetching multiple orders based on their ID numbers. E.g. `order_ids[]=1&order_ids[]=4&order_ids[]=56`


`GET /webhooks/changes`
Used for fetching orders based on their creation and edit dates. Returns 100 orders at a time starting from the indicated date.
`created_after_ts`	String	A starting point in time in the Unix timestamp format for fetching orders that were created after that point. E.g. `created_after_ts=1483185600`
`updated_after_ts`	String	A starting point in time in the Unix timestamp format for fetching orders that were updated after that point.


`GET /webhooks/send`
Used for resending a Webhooks message that failed.
`order`	Integers	Order ID number

Return values

All data returned by Webhooks is in XML format. You can see a Webhooks' response below in XML format.

See the sample file

The sample below is an answer to the GET /webhooks/changes request used for fetching orders from the online store.

The response contains order, orderer, and order product details.

<Orders>
  <Order id="58">
    <OrderNumber>58</OrderNumber>
    <OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
    <OrderStatus>Open</OrderStatus>
    <OrderLanguage>en</OrderLanguage>
    <Comments>To be processed quickly, more urgent than other orders.</Comments>
    <PaymentMethod PaymentID="7">Checkout</PaymentMethod>
    <PaymentReference>20120819001532</PaymentReference>
    <PaymentStatus>Paid</PaymentStatus>
    <ShippingMethod ShippingID="6">SmartPOST</ShippingMethod>
    <ShippingWeight>0.5</ShippingWeight>
    <ShippingPackages>1</ShippingPackages>
    <Documents>
      <Receipt>http://smo43.mycashflow.fi/orderstatus/58/receipt/52d07914f6bcdf448084320f3de6a816</Receipt>
      <DispatchNote>http://smo43.mycashflow.fi/orderstatus/58/dispatchnote/ba4be2b2ed682be3c646be5ef7f3a77d</DispatchNote>
      <Invoice>http://smo43.mycashflow.fi/orderstatus/58/invoice/f358b6fe49b80c91425137059e0cb49b</Invoice>
    </Documents>

    <CustomerInformation>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <BusinessID>FI21315706</BusinessID>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <Zipcodeph>87100</Zipcodeph>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Email allowMarketing="false">ismo@pulse247.info</Email>
      <Phone allowMarketing="false">020 741 9172</Phone>
      <IPAddress>85.29.85.227</IPAddress>
    </CustomerInformation>

    <ShippingAddress>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <Zipcodeph>87100</Zipcodeph>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Phone>020 741 9172</Phone>
    </ShippingAddress>

    <Products>
      <Product>
        <ProductID>3</ProductID>
        <ProductName>Lacoste light footware</ProductName>
        <Variation id="3">White/42</Variation>
        <codeph>123123</codeph>
        <UnitPrice vat="0">41.28</UnitPrice>
        <Quantity>1</Quantity>
        <Total>41.28</Total>
        <Shipped>false</Shipped>
      </Product>

      <Product>
        <ProductID>1199</ProductID>
        <ProductName>Gift card 100€</ProductName>
        <UnitPrice vat="0">66.12</UnitPrice>
        <Quantity>1</Quantity>
        <Total>66.12</Total>
        <Shipped>false</Shipped>

        <Campaign>
          <CampaignID>496</CampaignID>
          <NormalUnitPrice>82.6446</NormalUnitPrice>
        </Campaign>

      </Product>

      <Product>
        <ProductID PaymentID="7">PAYMENT</ProductID>
        <ProductName>Checkout</ProductName>
        <Quantity>1</Quantity>
      </Product>

      <Product>
        <ProductID ShippingID="6">SHIPPING</ProductID>
        <ProductName>SmartPOST</ProductName>
        <UnitPrice vat="0">5</UnitPrice>
        <Quantity>1</Quantity>
        <Total>5</Total>
      </Product>

    </Products>
  </Order>
</Orders>

Examples

You can see examples below of successful actions that can be carried out by using the Webhooks extension.

See all the detailed descriptions of all actions and the available parameters.

Fetching individual orders

You can fetch details of individual orders via your online store's Webhooks interface:

GET /webhooks/get?order=43&key=gvbnkiytfghu76tg

When fetching individual orders via the Webhooks interface, the response's root element <Order> will contain the order, orderer and order products details.

Fetching new orders

The Webhooks extension also enables you to send data about new orders that arrived at your online store to an external system.

GET /webhooks/changes?ts=n&key=jhbnji8765rfg

In standard implementations, the external system requests data about events that took place starting from a certain point in time from the interface and processes the orders. At the end, the system saves the timestamp of the last order and uses it in the next request.

An order list returned by Webhooks

<Orders time_from="1336738000" time_to="1345401893" orders="58">
	<Order id="1">
		<OrderNumber>1</OrderNumber>
		<OrderedAt timestamp="1336738023">2012-05-11 15:07:03</OrderedAt>
		...
	</Order>
	...
	<Order id="58">
		<OrderNumber>58</OrderNumber>
		<OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
		...
	</Order>
</Orders>

The response to the GET /webhooks/changes request is similar to the response received when individual orders are fetched, but the XML file's root element <Orders> contains an <Order> element for each order returned by the request.

The attributes of the <Orders> element contain information about the timespan from which orders are fetched and the total number of orders included in the material. The <OrderedAt> element used to describe individual orders has also been equipped with the timestamp attribute that indicates the order's timestamp.

You may want to process orders returned via the GET /webhooks/changes interface in order of appearance and, after successful processing, save their individual timestamps rather than the <Orders> element's time_to attribute. In this way, the next search will start from the first order that hasn't been processed, and it will also include orders for which processing previously failed.

Fetching selected orders

Multiple orders can be fetched at a time by using the following Webhooks requests:

GET /webhooks/get?order_ids[]=23&order_ids[]=43&order_ids[]=3&key=jhbnji8765rfg

When multiple orders are fetched, the response's root element <Orders> will contain a separate <Order> element for each returned order, just like the response to the GET /webhooks/changes request.

Marking orders and all their products as delivered

You can use Webhooks requests to mark orders as shipped. To do so, use the following parameters:

POST /webhooks/process
    action=deliver
    order=45
    send_email=1
    key=gvbnkiytfghu76tg

In the example, a shipping confirmation is sent to the customer by using the parameter send_email=1.

Adding order comments

You can add comments to the orders and, optionally, notify the customer about them. To do so, use the following request:

POST /webhooks/process
    action=add_comment
    message="Message contents"
    public_message=1
    key=jhbnji8765rfg

The example's comment is set as public (and therefore sent to the customer) by using the attribute public_message=1.

Resending Webhooks messages

A failed message can be resent by using the GET /webhooks/send request. The number for the order to be sent is included in the request's order parameter.

GET /webhooks/send?order=34&key=jhbnji8765rfg

USER GUIDE