Receive Formaloo events with webhooks
Using Formaloo's webhooks will help you to receive the important events on your forms automatically right as they happen. For example, instead of regularly checking to see if your form has any new submissions, using webhooks will send you a notification (along with the related data) as your form receives a new submission.
Each form can have multiple webhooks, each sending the notifications and data to a specific URL. Each webhook can handle multiple pre-defined events. Meaning when a webhook is added to a form, it can be called on multiple event types related to the said form.
Webhooks
Each webhook should have the following specifications:
A URL address that accepts POST data.
The response should have a
HTTP 200status code, along with an empty body.Optionally you can set a secret on your webhook, that will be sent in the request header with the
X-Formaloo-Tokenkey, so you can make sure that the webhook is called by Formaloo.
When a webhook event is called, we will send a POST request to the webhook address with the following specifications:
The body contains the event's data (e.g. the submitted form data). We'll explain more about this in the Events section.
The header contains the
X-Formaloo-Tokenif you have set thesecreton your webhook. The request body will contain the event-related data.
Each webhook request is deemed successful only when it receives a response with an empty body and an HTTP 200 status code. If sending the webhook fails, we will retry sending it multiple times with a few seconds of delay each time. If all the tries are failed after a set amount of tries, the event is deemed to be failed overall.
Adding webhooks to your forms
In order to add webhooks to your form, follow these steps in the Formaloo form maker dashboard:
Select the form from your list.
Go to the Integrations and Webhooks tab.
Click on the Webhook List button to open the Webhook management window.
Enter the webhook data and turn on the desired events.
Use the webhooks list to manage the existing webhooks.
Events
Each event represents an action in the system, that you want to automatically know right after they happen, and receive their data as well. For example, you want to call a function on your system whenever a form is submitted, without checking the list of submits over API waiting for an update.
Currently, our webhooks support three form-related events, which are the following:
Form submit event
This webhook is called whenever the form receives a new submit, either by the end-user or by the form admin. This event is called right after the form is submitted and sends the submitted data, calculations data, and some basic data (e.g. submit time) to the webhook URL. Please note that this event won't be called after a row is edited by the admin or its payment status is updated.
For payment forms use the Form payment event.
Data Example
An example of data sent to the webhook for a form that takes the user's full name and phone number:
{ "event_type": "form_submit", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423" }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-19T14:57:43.796281+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
Note: The data key contains the raw data without any metadata. It comes in handy if you're using Formaloo API to get the fields' full data, and you can translate the data yourself. Otherwise, the rendered data contains everything you need to know about the submitted data.
Row update event
This webhook is called whenever a row on the form is edited. This event is called right after the row is edited and will send the full row data to the webhook URL.
Data Example
The example form takes the user's full name and phone number
{ "event_type": "row_update", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423" }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-13T10:23:43.234323+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
Form payment event
This event is called when a payment transaction is completed. Meaning, the user has submitted a payment form, and successfully completed the payment process. This event will send all the submitted data (just like the form submit event), along with the payment data. Like payment amount, order code, etc.
If you activate both the form submit event and the form payment event on the same form, you will receive two events for a successful payment, one right after the submission is created and one after the payment is successfully finished. So if you do this for any reason, make sure to handle the data properly to avoid any duplication. (For example, update the existing record after the payment event is received instead of creating a new record).
Data Example
Suppose users select their food from a list and pay for it. The payment data is added at the end of the rendered_data list.
{ "event_type": "row_payment", "event_id": "xEJsGn", "data": { "field_QkcERTTt": "+1677673423", "field_cfUkTmtq": "choice_kQqwcAXH", "field_tClRSgaU": "Joh Doe" }, "rendered_data": [ { "slug": "field_tClRSgaU", "type": "short_text", "title": "Full Name", "value": "Joh Doe", "json_key": null, "position": 1, "raw_value": "Joh Doe", "admin_only": false, "json_value": null, "max_length": 255 }, { "slug": "field_QkcERTTt", "type": "short_text", "title": "Phone Number", "value": "+1677673423", "json_key": null, "position": 2, "max_value": null, "min_value": null, "raw_value": "+1677673423", "admin_only": false, "json_value": null }, { "slug": "field_cfUkTmtq", "type": "dropdown", "title": "Select the food you want to buy", "value": "Pizza", "json_key": null, "position": 3, "raw_value": "choice_kQqwcAXH", "admin_only": false, "json_value": null, "delta_score": { "grade": 0.0, "currency": 15.0 }, "choice_items": [ { "slug": "choice_zrKaPTwY", "image": null, "title": "Pasta", "deleted": null, "json_key": null, "position": 1, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" }, { "slug": "choice_mTpKFfXl", "image": null, "title": "Burger", "deleted": null, "json_key": null, "position": 2, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" }, { "slug": "choice_kQqwcAXH", "image": null, "title": "Pizza", "deleted": null, "json_key": null, "position": 3, "created_at": "2021-07-25T11:14:07.806553+04:30", "updated_at": "2021-07-25T11:14:07.861721+04:30" } ] }, { "slug": "order_status", "title": "Order Status", "value": "Successful", "json_key": null, "position": -1 }, { "slug": "order_code", "title": "Order Code", "value": "4908799754916322", "json_key": null, "position": 1000 }, { "slug": "payment_amount", "title": "payment amount", "value": 15.0, "json_key": null, "position": 999 } ], "readable_data": { "Full Name": "Joh Doe", "Phone Number": "+1677673423", "Order Status": "Successful", "Order Code": "4908799754916322", "payment amount": 15.0 }, "created_at": "2020-11-19T14:57:43.796281+01:00", "updated_at": "2020-11-13T10:23:43.234323+01:00", "submit_code": "UZF9XpVgY4sr5zmF", "slug": "ZNtjCuScAjt349Rf" }
Adding webhooks to forms
Each form can have multiple webhooks. You can define a webhook on a form, and manage it, e.g. seeing a list of a form's webhooks, editing or editing the webhooks, and creating more webhooks. If you create multiple webhooks on a single form, the related forms will be sent to all of them separately.
Create A Webhook
You can create a webhook on a form by sending a POST containing the following fields to its Endpoint:
Endpoint: https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/
Method: POST
Fields:
url (required) The webhooks address.
secret (optional) A secret key to send in the webhook requests' header as X-Formaloo-Token.
form_submit_events (optional, defaults to false) Should we send a webhook event on form event?
row_update_events (optional, defaults to false) Should we send a webhook event when a row is updated?
row_payment_events (optional, defaults to false) Should we send a webhook event on each successful payment event? (Won't have any effect on forms without payment)
active (optional, defaults to true) Is the webhook currently active? (Mostly comes in handy on editing, while disabling a webhook rather than deleting it).
send_rendered_data (optional, defaults to false) include rendered_data in the data of webhook or not.
send_raw_data (optional, defaults to false) include raw data in data of webhook or not.
Example
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/ (POST) { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": true, "send_rendered_data": true, "send_raw_data": true } // Respone { "status": 201, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhook": { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_payment_events": true, "row_update_events": true, "send_rendered_data": true, "send_raw_data": true "active": true, "created_at": "2021-09-04T16:29:10.808996+04:30", "updated_at": "2021-09-04T16:29:10.809010+04:30", "slug": "FVyTMf7o" } } }
Get A Forms' Webhooks
You can simply get a list of the form's webhooks by sending a GET request. The result is a non-paginated list of webhooks:
Endpoint: https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/
Method: GET
Example
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/ (GET) // Response { "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhooks": [ { "url": "https://example.com/webhook/", "secret": null, "form_submit_events": false, "row_update_events": true, "row_payment_events": false, "active": true, "created_at": "2021-09-04T16:17:44.360965+04:30", "updated_at": "2021-09-04T16:17:44.360982+04:30", "slug": "xyLY8zjx" }, { "url": "https://example.com/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": false, "active": true, "created_at": "2021-09-04T16:28:23.811015+04:30", "updated_at": "2021-09-04T16:28:23.811030+04:30", "slug": "AWTTuWEp" }, { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": false, "row_payment_events": true, "active": true, "created_at": "2021-09-04T16:29:10.808996+04:30", "updated_at": "2021-09-04T16:29:10.809010+04:30", "slug": "FVyTMf7o" } ] } }
Get A Webhook Object
You can get a webhook object using its slug, although all the data is also included on the webhook list.
Endpoint: https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/{WEBHOOK_SLUG}/
Method: GET
Example
// Request https://api.formaloo.net/v1.0/forms/{FORM_SLUG}/webhooks/{WEBHOOK_SLUG}/ (GET) // Response { "status": 200, "errors": { "general_errors": [], "form_errors": {} }, "data": { "webhook": { "url": "https://example.net/webhook/", "secret": "SOME_SECET_TEXT", "form_submit_events": true, "row_update_events": true, "row_payment_events": true, "active": true, "created_at": "2021-09-04T16:37:26.920125+04:30", "updated_at": "2021-09-04T16:37:26.920141+04:30", "slug": "FW1Otww5" } } }