Custom Workflows, Custom Webhooks and The Workflows API

The "Custom" workflow type is a special kind of workflow that can be used to run actions arbitrarily on a schedule, on-demand, or by using the Workflows API (Custom HTTP Request).

Custom Workflows vs. HTTP Request Actions

Custom Workflows are ideal for sending arbitrary data to Arigato for processing, like processing a custom webhook payload. Schedules and Bulk Operations within Custom Workflows are simply other ways of triggering a Custom Workflow, aside from an incoming webhook.

The HTTP Request action type is ideal for making HTTP requests from the app to another service. HTTP Request actions are an Action available for configuration on any workflow. 

Getting Started  

To create this type of workflow select "Custom" when creating a new workflow:

If you select the trigger "Run in a bulk operation" you will be able to create a bulk operation to run the actions in the workflow. For example, you could set up a nightly bulk operation that makes a Shopify API Request to the "/orders" endpoint and emails you a list of all orders placed in the past 24 hours.

If you want to trigger the workflow using a Custom HTTP Request, see The Workflows API documentation below.

The Workflows API

The "Custom" workflow type allows you to run the workflow by sending a POST, PUT, or DELETE request to a unique API URL. GET requests are not supported, however, if you navigate to the API URL in your web browser you will be presented with a form to test the workflow.

To create this type of workflow, create a new "Custom" workflow and select "Custom HTTP Request" as the trigger type.

At the top of the workflow edit form will be a unique, public URL for the workflow that looks like:

https://apps.bonify.io/api/triggers/workflows/{id1}/{id2}/{unique_token}

HTTP Request Conditions

The "Custom" workflow type lets you create conditions based on the incoming request. Some common conditions include checking the request Method, Headers, and JSON data that has been passed to the workflow. If your trigger type is "On a schedule or on-demand", these conditions generally do not apply.

HTTP Method

This condition will ensure your actions are only run for a specific request method. You can have a single workflow that contains multiple condition groups that check for various request methods, so a single workflow could perform different actions when receiving a POST, PUT, or DELETE request.

If you do not have a condition based on the HTTP Method your workflow will run for ALL METHODS.

Screenshot_2020-03-30_14.52.22.png

Headers

This condition checks the value of a specific header. You could use this condition to force an additional security check by passing a secure header string.

Screenshot_2020-03-30_14.54.49.png

JSON

This condition lets you check the value of any data passed as JSON in the request. For example, if your workflow requires that a "product_id" value is passed in the JSON you could add a condition for:

Screenshot_2020-03-30_14.56.52.png

Request JSON Tokens

Data passed into the request is available as tokens. You can use these tokens in your conditions and actions.

For example, to get a "product_id" value passed as JSON in the request, you could use the token:

{{ http_request.json.product_id }}

As an example, if your workflow has an action to set a product metafield value, you could pass the following JSON in a POST request:

{
  "product_id": "123123123", 
  "value": "just a test",
  "namespace": "custom_fields",
  "key": "test"
}

Your metafield action would then look like:

Screenshot_2020-03-30_15.02.26.png

Testing the Workflows API

You can test your custom workflow easily by navigating to the API URL in your browser. Because GET requests are not supported in the Workflows API, you will see a simple form that will allow you to perform POST, PUT, and DELETE requests to the workflow.

The form will look like this:

Screenshot_2020-03-30_15.13.01.png

Our workflow to set a product metafield value looks like:

Screenshot_2020-03-30_15.09.46.png

Let's try running the workflow using the following values (notice we are using a PUT request and are missing the product_id value that the workflow is expecting):

Screenshot_2020-03-30_15.10.24.png

When you click "Run Workflow" you will see the response. The response shows that the conditions failed, and shows which conditions failed.

Screenshot_2020-03-30_15.10.40.png

If we fix the request by changing the method to POST, and adding a "product_id" value we get a successful response:

Screenshot_2020-03-30_15.11.16.png

Workflows API Response Codes

Responses to the Workflows API are in JSON, and they always contain the following:

{
  "status": "okay" OR "error",
  "message": "More info about the status"
}

An "okay" status generally means that the workflow has run, and the actions have queued. The HTTP Status code will be 200 OK.

Note: Just because the actions have queued does not mean they have been run successfully. Due to the asynchronous nature of the queue processing system, you must verify actions have run by checking the Logs page in app.

Error Codes

If there is an error in the API request, an HTTP status code in the 4XX range and a JSON message with more info will be returned.

Possible error messages include:

method_not_allowed (code 405)
Only POST, PUT, and DELETE requests can be sent to the API.

invalid (code 401)
The request is invalid, likely caused by the URL being malformed or modified.

too_many_requests (code 429)
The API is currently limited to an average of  2 requests per second. Shorts bursts of up to 120 requests per minute can be made. If the limit is hit you must wait at least 10 seconds to continue making requests.

invalid_trigger_type (code 403)
The workflow is not using the "Custom HTTP Request" trigger type.

workflow_paused (code 403)
The workflow is paused. You must "Resume" the workflow in order to make API requests to it.

conditions_failed (code 403)
One or more conditions failed and the workflow will not run. Additional details are returned in the "results" field.

unknown_error (code 403)
Unknown error has occurred, possibly caused by invalid Twig syntax in a condition or action. Please contact us using the Live Chat feature in app to get help diagnosing.

Security Precautions

  • Keep your unique token secret.
  • This system is designed to be accessed through backend systems only. 
  • Never use this system on a website front end via javascript as you will be exposing your unique secret token. 

Related Articles