Connect your Webhook

Introduction

Webhooks are “user-defined HTTP callbacks”. They are usually triggered by some event, such as pushing code to a repository, a login or clicking on a unique link. When that event occurs, the source site makes an HTTP request to the URL configured for the webhook. You can connect your webhook to our platform to use it in your flow as a trigger to restart the flow or continue its execution.

In this example, we are going to set up a webhook that is going to listen to some changes in our webshop:

  • customer_order: when a customer makes an order.
  • order_delivered: when an order has been delivered.

In our case, in order to test the final process, we are going to send these statuses manually by making CURL requests.

These are the steps that are going to be covered:

  1. Set up our data scheme
  2. Create our interface
  3. Set up our webhook
  4. Design our templates and contents
  5. Build the flow
  6. Test the process

Set up our data scheme

Our data scheme must basically look as follows:

{
   "id": "",
   "name": "",
   "email": ""
}
  • id: the customer’s id.
  • name: the customer’s name.
  • email: the customer’s email.

For more information on how to set up our JSON data scheme, please visit this link.

Create our interface

The next step is to set up the structure of the data that our interface will receive and map it against our data scheme.

In this example, we are going to call it Webshop and it is going to use exactly the same payload as our data scheme. Our mapping should look as follows:

The scope available must be batch and record in the authorization tab.

For further information on how to create an interface, please refer to this page.

If you need to know more about how to configure an interface, please visit this post.

Set up our webhook

When creating a webhook, a unique URL will be generated for you. You can use this URL (example: https://api.flowize.io/v1/webhook/xxxxxxxxx) to push the callback.

In order to create the webhook, we need first to go to the webhook URLs overview and click on the “New Webhook URL” button:

Now we enter the name of our webhook URL and the app that is going to be based on. In our case, it is going to be My Apps as it is a custom webhook. After this, we click on the “Save” button.

This will take us to the configuration page of our webhook URL:

We configure it as shown above and we click on the “Save” button.

The next thing we need to do is to add the object that we will, later on, use in the flow. To do so, we click on the “Add a new flow object” button:

Let’s configure this flow object:

Information

Parameters

Now we need to set the webhook unique identifier that will be used, later on, in the flow and our custom statuses.

We have to click on the “Edit information” button to add our custom statuses:

After applying the changes, we will see that our statuses were added:

Incoming request

The last part of the configuration involves defining the data that the webhook is going to receive:

In our case, we will receive a list of the products that the order contains and its total price.

If you need more information on how to configure a webhook, please refer to this link.

Design our templates and contents

You can download all needed templates by clicking on this link.

Once we are done with this, we create the HTML contents based on these templates that we just created. It is important to keep in mind that we need to publish these contents in order to be able to use them in the flow.

The Order content will be sent when a new order is placed and the Invoice when an order has been delivered.

Build the flow

We are going to name this flow Webshop. This is the configuration of our webhooks:

  1. Customer ordered: when this webhook is called our flow will send an email to the administrator to inform him that a new order was placed.
  2. Order delivered: when this webhook is called our flow will send an email to the customer to inform him that his order has been delivered.
  3. Email to customer: In this object, we should use our Invoice HTML content.
  4. Email to admin: In this object, we should use our Order HTML content.

We have made both webhooks persistent cause we want them to be listening to new statuses till the flow ends.

If you need more information on how to create a flow, please visit this link.

Test the process

In order to test the process, we are going to send a bunch of customers to the system.

In this case, we are going to send the following CURL request in order to insert the batch of records:

curl -X POST \
  https://{{platform_api_url}}/v1/batch \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'X-Apikey: {{put_here_your_api_key}}' \
  -H 'X-App: Webshop' \
  -H 'X-Batch-Status: ready' \
  -H 'X-Flow: Webshop' \
  -H 'X-Scopes: batch' \
  -d '[
	{
          "id": "000000001",
          "name": "John Doe",
	  "email": "john.doe@email.com"
	},
	{
          "id": "000000002"
	  "name": "Steven Wonder",
	  "email": "steven.wonder@email.com"
	}
]'

You must replace {{platform_api_url}} by the API URL and {{put_here_your_api_key}} by your API key.

Finally, we are going to trigger both statuses manually. These are the two needed CURL requests:

Customer 1 made an order

curl -X POST \
  {{insert_here_your_webhook_url}} \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"id": "000000001",
	"status": "customer_order",
	"total_price": "20.00",
	"products": [
		{
			"name": "Product #1",
			"description": "This is the first product",
			"quantity": "2",
			"price": "10.00"
		},
		{
			"name": "Product #2",
			"description": "This is the second product",
			"quantity": "5",
			"price": "10.00"
		}
	]
}'

Customer 2 received his order

curl -X POST \
  {{insert_here_your_webhook_url}} \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
	"id": "000000002",
	"status": "order_delivered",
	"total_price": "11.00",
	"products": [
		{
			"name": "Product #1",
			"description": "This is the first product",
			"quantity": "1",
			"price": "5.50"
		},
		{
			"name": "Product #2",
			"description": "This is the second product",
			"quantity": "1",
			"price": "5.50"
		}
	]
}'

In both cases, you must replace {{insert_here_your_webhook_url}} by the webhook URL. You can get this in the webhook URL overview.

Congratulations! You have successfully connected your webhook.