This article is also available in:

Webhooks

You can share information from your forms in Flokzu with external systems through webhooks.
Webhooks provide a notification mechanism to your app when a certain event happens so that you are able to take action on that. In Flokzu those events can be:

Save
Task completed

Action will depend on your external system and you will have to set up the URL to execute it.

How do webhooks work?

Imagine a doorbell system, it includes a button on the door and a bell in your living room.
When a person presses the button, the bell rings in the room, letting you know that someone is at the door - that is, a signal is sent from the button to the doorbell.
In this example: someone will come to the door and press the button, the bell will hear the button and ring.

Webhooks work the same way, the door will be Flokzu, the button will be the event that happens in Flokzu and the bell the system that you notify of that event.
For webhooks: An event will happen on Flokzu, the other system will listen to that event and perform an action based on it, for example Update data.

Webhook type_save_

A webhook configured for the save event will be executed every time one of this actions happen:

At creating a new instance (whether that is a logged in user or a public form)
At executing the autosave and the explicit save, only if the form was changed.

WebHook type task completed

A webhook configured for the task completed event will be executed every time a task is completed.

When a webhook will NOT be executed? Webhooks won’t be executed in tasks completed by a timer or conditional event.

Setting up webhooks

Webhooks can be enabled and configured for each process. To do so, go to the Configuration tab of the process in question and in the Webhooks section you will be able to enable it.

There you will be able to configure the URLs that will be invoked when the different types of events occur as well as generate a token to add to the header of the call to provide security to it.

General format of the message sent to webhooks.

json
{ 
 "Timestamp": "date of the event in UTC format",
 "Type": "save o task_complete", 
 "Payload": "JSON according to the event"
}

Message format for a webhook of type save

In the property Payload of json the complete document that was modified will be sent.

The format will be as follows:

{
"tenantName": "tenant name",
"reference": "doc reference",
"documentCreator": "doc creator",
"dateCreated": "document creation date",
"info": " document summary",
"tags": ["tags of the document separated by comma"],
"downloadKey": "id document",
"fields": [
                   {"field 1": "value 1"},
                   {"field 2": "value 2"}	
 ]
}

json contains the name of the tenant to which the document belongs, its reference, the creator of the document and the date it was created in ISO 8601 format.
You will also find the special fields summary (in the property info ) and tags (in the property tags), as well as the document ID (property downloadKey).

In the property fields you will find all the fields defined by the user and the values of these will be seen in the following way:

- Email,one line text,multilinear text, link, integer, decimal, auto-calculated, date and time, show the value exactly as they are in the document.
- Combo box and radio button, show the selected value.
- Multi-selection combo and checklist, show an array with the selected options and separated by inverted commas.
- Table, shows table name, and then for each record, the columns and its correspondent value.
- Attachment, shows info related to it such as name, attachment id, date of creation and more.
- Yes/No, shows true if the selected option is yes and false if not.
- Rich text, shows the content of the field with its correspondent tags to generate the same content as in the Flokzu document.
- Signature, not supported.

Example:

json sent:

{
 "tenantName": "Flokzu",
   "reference": "PED-14",
   "documentCreator": "leandro@flokzu.com",
   "dateCreated": "2019-08-06T17:17:10.223Z",
   "info": "",
   "tags: [""],
   "downloadKey": "b45602d6467856c5b2a45973c49a99e2",
   "fields: [
                {"Email": "nombre@gmail.com"},
                {"Name": "John Smith."}
                {"Description": "Request for office stationery supplies"},
                {"Number of items": "2"},
                {"Total amount": "3505.5"},
                {"Date": "06/08/2019"},
                {"Time": "15:30:00"},
                {"City": "Madrid"},
                {"Method of payment": "Cash",}
                "{"Suppliers": "[Bolimax", "Rollerpen", "AllUSB",}
                "{"Category": "[Stationery], "Computer science",} 
                {"Order": [
                            {"Product": "Pen",
                             "Quantity": "150"
                             "Price": "750",} 
                            {"Product": "Pendrive",
                             "Quantity": "11"
                             "Price": "2755.5"}
                           ]},
                {"Detail of the order": {
                                "attachmentId: "badbf0e134604c54907ac960a5f862c9",
                                "name": "detalle.pdf",
                                "mimeType": 50,
                                "superType": 0,
                                "creationTime": "2019-08-06T17:16:08.479Z",
                                "size: 47939,
                                "lastEditedUtc": "", 
                                "url": ""
                                    }},
                {"Active account": "true"},
                {"Web": "www.flokzu.com"},
                {"Number of items": "161"},
{"Observations":"<pstyle="text-align:center;\"><strong>Observaciones:</strong></p>\r\n<p style=\"text-align: center;\">&nbsp;</p>\r\n<p style=\"text-align: left;\">Deliver to street 1234 from 08 to 18 hs..</p>"}
              ]
}

Message format for a webHook task completed type.

The json property Payload will send the task and the user who performed it.
At the same time it will be informed which action was carried out to complete the task and the corresponding date.
It will also have the information of the date in which the task was created (UTC format).
The format will be as follows:

{
"task_name": "name of the completed task",
"last_participant": "user who completed the task",
"last_action": "decision made for the task to be completed",
"reference": "doc reference",
"start_date": "date the task was created",
"end_date": "date the task was completed"
}

The active version doesn’t have a Retry Policy. To ensure data integrity in your implementation, you can use the event timestamp.
As an example, it might be useful to check that a delayed call to your web service does not overwrite a data in your system that was updated by a later call in time.

Test webhooks

To test how webhooks work you can go to https://webhook.site/. This site will provide you with a URL for your tests.

You must put that URL in the Webhooks section in the Process Settings tab of your process. You can use it both for the instance creation / save and for the completed task event.

Once added there you must deploy the process, create an instance and / or complete it and you will see the webhook in action.

Sample creation / save response

Sample response to task completed

Updated on: 09/06/2022

Was this article helpful?

Thank you!