Toggle Side Panel
Close search
View Categories

Webhooks

8 min read

What are Webhooks? #

Webhooks provide a way for one system to send a notification to another when an event occurs. It’s more efficient than frequently querying to see if there’s new data to process (also known as “polling”). Instead, when there’s work to be done, that system sends it over.

Types of Cyclr Webhook #

Cyclr provides support for Webhooks in several ways, where external systems can send data to be processed by your integrations, or to trigger actions within them:

Note: Cyclr also supports a Partner-level Webhook feature referred to as the “Singular Partner Webhook URL” which works against a particular Connector. It’s implemented by certain Application Library Connectors where an external system will send notifications to a single URL for all of its users, and Cyclr will then route them to the appropriate Cycles within your Accounts using the details it contains.

The “Singular Partner Webhook URL” can also be used when building a Custom Connector.

Webhooks within Cyclr #

Webhook URLs #

Every Step in your Templates and your Cycles that uses a Cyclr Webhook will have a unique (and unmodifiable) URL for it to receive requests through. The random characters on the end are referred to as the “Webhook Identifier”:

https://YourCompany-h.cyclr.com/api/webhook/XXXXXXXX

Note: If you only have the Cyclr Webhook URL and don’t know where the Template or Cycle it relates to is located, you can use the unique end part – the “Webhook Identifier” – in the Console’s Webhooks Report to track it down.

Having dragged any Webhook Method or Tool into the Builder, you can view its URL by clicking its Step Setup button:

Note: “Webhook” Methods Connector Methods can be configured so that Cyclr automatically subscribes them into the external system, if that system’s API supports it.

In those situations, a Step using that Connector Method won’t immediately show its URL and will display a button to view it and a note stating:
“When you start the cycle, this webhook will be automatically created”

Sending Requests to Cyclr Webhooks #

Cyclr’s Webhooks expect HTTP POST requests to be sent to them, with data located in the request’s body.

Content sent in the body of a POST request can be JSON, XML, Form, etc as described here. What’s being sent should be indicated using the request’s Content-Type HTTP Header so it is interpreted correctly.

HTTP GET requests are accepted, but they won’t result in Transactions being created within your Templates or Cycles. Read more on what you can do with GET requests and Webhooks using Script.

Note: See Payload Size Limitations for the maximum size of data you can send to a Cyclr Webhook.

Asynchronous vs Synchronous Webhooks #

Integrations in Cyclr that start with a Webhook Step are typically asynchronous: when a request is sent to the Webhook, a response is sent back immediately to confirm whether the request was accepted or not. If it was accepted, Cyclr will go on to run the integration using the data it was given. That could happen immediately, or it could be queued for processing later if other Transactions are already in progress.

This gives a “fire and forget” process: you tell Cyclr to do some work and it says “OK – I’ll do that” which may be straight away, or could happen some time afterwards.

If you use a Webhook Step and include a Synchronous Response Step in an integration, Cyclr’s behaviour changes to synchronous:

It will receive a request on the Webhook Step as normal, but rather than just sending an “OK” response straight away, it will keep the connection open and run through the rest of the Cycle.

Once a Synchronous Response Step is reached, Cyclr will send back a reply with what’s been set on that Step as the response to the calling system through that same connection.

You can define what goes back in the response using the Synchronous Response’s Step Setup.

Using a Webhook in a Cycle that includes one or more Synchronous Response Steps allows you to tell Cyclr to do some work and remain connected to send back a response.

We refer to that setup as a “Synchronous Webhook”.

You can use multiple Synchronous Response Steps in an integration, enabling you to set different responses to be sent back, depending on the route a Transaction takes through it.

This allows you to implement an integration that perhaps accepts a value to search for:

  • If it finds a match, the matching data could be returned using one Synchronous Response Step.
  • If it’s not found, a second Synchronous Response Step could be used to return a “not found” result.

The example below demonstrates how this could be setup:

Mid-Cycle Webhooks #

Webhook Steps are often used as the first Step in a Cycle as a way to receive data for processing, but they can also be used part-way through a Cycle – or “mid-Cycle” – as a way of holding a Transaction until it’s ready to proceed:

One example of why a Transaction might need to be held could be when performing some remote setup or requesting an intensive data query to be executed; tasks that could take anywhere from a few minutes to several days to complete.

A Transaction will run through a Cycle as normal until it reaches a mid-Cycle Webhook Step. There it will wait until the Webhook Step receives a request indicating that Transaction can continue.

Mid-Cycle Webhooks have a Webhook Mapping section in their Step Setup popups where you define what will trigger a Transaction to continue. You select the property to use when the mid-Cycle Webhook Step receives requests to its Webhook URL that will contain a value that matches another property found in the existing Transactions, e.g. a Job or Order ID – something that identifies a particular object:

Each time the mid-Cycle Webhook receives a request to its URL, it will search for the most recent Transaction with a matching value for the Webhook Mapping defined, and run that Transaction from there.

This can occur multiple times, causing a single Transaction to be run from the mid-Cycle Webhook more than once.

This is useful when processing data such as Orders where a notification might be received each time its status changes (e.g. from Received, Picked, Packed to Despatched). In that situation, if you only wanted to continue when an Order’s status was “Despatched”, you could use a Decision Step after the Webhook Step to check the current status.

Note: Transactions can only continue from a mid-Cycle Webhook if they still exist and haven’t been removed by Data Retention settings.
The maximum amount of time a Transaction can therefore be retained is 31 days.

Webhook Status Codes #

When a request is sent to a Cyclr Webhook Step, depending on the running state of the integration it’s located in, Cyclr will respond as described here:

Responses to HTTP “POST” requests #

Cyclr responds with the following HTTP Status codes and responses when an HTTP POST request is sent to a Cyclr Webhook URL:

HTTP Status Code:  406 Not Acceptable
Response Body:     Please make sure your webhook is active.
  • Integration Status:
    • The integration has never been started.
    • The integration had previously been started, but has since been stopped for over 24 hours.
  • Behaviour:
    • Cyclr will not queue or process requests.
HTTP Status Code:  200 OK
Response Body:     Webhook accepted.
  • Integration Status:
    • Integration is currently running.
    • Integration has been started, but was stopped within the last 24 hours.
  • Behaviour:
    • Cyclr will either process the requests or queue them for processing once the integration is restarted, provided that is within 24 hours from when it was stopped.
    • Responds in the same way so that external systems aren’t aware and continue sending requests.
HTTP Status Code:  404 Not Found
Response Body:     Webhook not found.
  • Response when a request is sent to an invalid Cyclr Webhook URL.

Responses to HTTP “GET” requests #

Cyclr’s Webhooks expect HTTP POST requests to be sent to them, with data located in the request’s body, as described here.

Sending an HTTP GET request to a valid Cyclr Webhook URL always results in the following response, regardless of the running state of the integration, but it won’t create a Transaction:

HTTP Status Code:  200 OK
Response Body:     Webhook found.

Scripting with Webhooks #

As with other types of Connector Methods and Steps, you can also use Script on Webhooks with the Webhook event functions.

Some examples of what you can do:

  • When receiving a request, you can modify the data that’s being received, perhaps by performing a calculation on its data or restructuring it to better fit your use-case.
  • To check the data before deciding whether it should be processed as a Transaction.
  • To convert an HTTP GET request into an HTTP POST request so that Cyclr will process it as a Transaction.