Toggle Side Panel
Close search
View Categories

Webhooks

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

Having dragged any Webhook Method or Tool into the Builder, its URL can be viewed 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 part.

Content sent in the body part 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 also 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.

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.