Articles on: Developers
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
  • Delete instance
  • Activate timer or non-interrupting conditional event in the instance


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:


  • A new instance is created (either by a logged-in user, through a public form, or through the Flokzu API).
  • Automatic saving or explicit saving is executed, as long as changes have been made to the form.


WebHook type task completed


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



Webhook execution in automatic actions and deletions


Webhooks can also be executed when an instance advances through automatic actions, such as timers or conditional events, and when an instance is deleted.


This allows information to be sent to external systems in more scenarios, maintaining a more complete trace of what happens in the instance.


The supported cases are:


  • When an instance advances through an interrupting or non-interrupting conditional event, a webhook of type Task Complete is sent.
  • When an instance advances through an interrupting, non-interrupting, or intermediate timer, a webhook of type Task Complete is sent.
  • When an instance is deleted, a webhook of type delete is sent.
  • When timers or non-interrupting conditional events are executed, a webhook of type event_triggered is sent.




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, task_complete, event_triggered or delete", 
 "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:


The following is an example of the json sent for a form with the following fields and values:


Field name | Data type | Value |

  • Email | email | nombre@mail.com |
  • Name | Text a line | John Doe |
  • Description | Multi-line text | Request for office stationery supplies|
  • Number of items | Integer | 2 |
  • Total amount | Decimal number | 3505.5 |
  • Date | Date | 06/08/2019 |
  • Time | Time | 15:30:00 | *
  • City| Combo options | Madrid |
  • Form of payment | Radio Button | Counted |
  • Suppliers | Multiselection Combo | Bolimax, Rollerpen, TodoUSB |
  • Categories | Checklist | Stationery, Computers |
  • Order | Table |Product: Pen, Quantity:150, Price:750; Product: Flash Drive, Quantity:11, *Price:2755.5|
  • Detail of the order | Attachment | |
  • Active account | Yes/No | Yes |
  • Web | Link | www.flokzu.com |
  • Number of items | Self-calculated | 3 |
  • Observations | Rich Text | Deliver to street 1234 from 08 to 18 hs.|




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"
}

Message format for an event_triggered webhook


In the Payload property of the JSON, the information related to the triggered event will be sent, including the event name through event_name, the associated document reference through reference, and the date when the event was executed through triggered_date.


{
  "Timestamp": "Date when the event occurred in UTC format",
  "Type": "event_triggered",
  "Payload": {
    "event_name": "name of the triggered event",
    "reference": "document reference",
    "triggered_date": "date when the event was executed"
  }
}


Message format for a delete webhook


In the Payload property of the JSON, the information related to the deleted document will be sent.


{
"Timestamp": "Date when the event occurred in UTC format",
"Type": "delete",
"Payload": {
"tenantName": "tenant name",
"reference": "document reference",
"documentCreator": "document creator",
"dateCreated": "document creation date",
"info": "document summary",
"tags": ["document tags separated by commas"],
"downloadKey": "document ID",
"fields": [
{"field 1": "value 1"},
{"field 2": "value 2"}
]
}
}



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**






Example response for event_triggered



Example response for delete




Updated on: 20/08/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!