The most robust way to receive data during a flow's progress and completion is to set up an endpoint for ingesting webhooks. Formsort sends data to this endpoint after a step is completed by the responder.
The frequency of sending data to the webhook can be configured as:
On Finalize: only at the end of the flow.
On Savepoint: after each step marked as save point, and at the end of the flow.
Every step: at the end of each step (when the responder advances using the Next button), and at the end of the flow.
Debounced: when the responder abandons the flow after a period of inactivity, and at the end of the flow. Formsort recommends using this setting to reduce the load on the webhook.
Formsort backend system will exclusively send webhook requests from the static IP 22.214.171.124.
To reduce the possibility of data loss, any unsuccessful call to the webhook endpoint will be retried up to 13 times in an exponential backdown fashion, starting with a wait of 1 second and delaying the last retry to about 2.5 hours. Formsort's timeout for the first retry is currently set to 15 seconds.
It's worth noting here that while we can guarantee at-least-once delivery, we cannot guarantee only-once delivery. All integration targets should be designed with idempotency in mind, and any targets that don't receive the webhook payload before the 15 second wait expires will receive a retries until successful. Receiving a duplicate answer submission should not adversely affect processing.
Shape of the data
The webhook is a POST of JSON data in the following shape:
If you'd like the responder uuid to be included, you can give it an alias in the webhook configuration.
It's possible to change the shape of the data, for example to nest the answers under their own key, or put them into an array.
The finalizedfield indicates that the flow has been completed. The value of finalized will betrue when any of the following conditions are met:
All questions in the final step of the form have been answered, submitted, and the user has clicked Next.
All questions in any step with the Is Terminal option toggled on have been answered, submitted, and the user has clicked Next.
The user is redirected in the current tab.
The user is redirected to a new tab AND either conditions 1 or 2 above are met. In other words, the current step is the final step of the form, or the current is step has the Is Terminal option toggled, and all answers have been answered, submitted, and the user has clicked Next.
You can send a test webhook with dummy data for a variant with the Send test webhook button, or just inspect a sample webhook body with the View webhook payload button.
If you'd like the requests to be signed to ensure that they are authentic requests from formsort, you can enable the sign security.
To generate the signature for verification, use the original HTTP request body (aka JSON payload) and:
Hash it with SH256, encrypt it with signing key.
Base64 encode it, but in a URL-safe-way, using - and _ instead of the + and / characters. This is necessary as Formsort sends the signature in the HTTP header.
Remove the trailing = signs. Those are often generated by the hashing libraries as padding.
The payloads will be signed with the following Python code. You can obtain the key in the Integrations tab when this option is enabled.
defhmac_sign(signing_key, original_request_body):# unmodified, a jsonified string
key = as_bytes(signing_key)
message = as_bytes(original_request_body)
# 1. for url safety, use - and _ characters instead of + and / respectively
# 2. remove the padding = signs at the end of the signature
hmac.new(key, message, hashlib.sha256).digest())
Setting up the Webhook Integration
Formsort makes it easy to get a webhook integration set up. By adding the Webhook URL, Formsort will immediately start sending answer data to the webhook destination at the frequency you've selected.
First, head to the webhook integration menu in your flow
All integrations, including webhooks, can be customized on a per-flow basis.
The Webhook integration menu
Change the webhook posting frequency to the desired frequency. Refer to Posting Frequency for a more in-depth explanation. Once your posting frequency is selected, the menu will open and you can add your Webhook URL.
Adding a Webhook Posting Frequency will open the menu
Add any other configuration options you require (covered in this chapter). If you'd like to add more than one webhook configuration, proceed to Adding multiple Webhook instances. Otherwise, Save the configuration with the Save button in the top right corner. Once saved, Formsort will begin sending the answers it collects from deployed flows to the webhook destination.
If you have deployed flows previous to integrating with your webhook, it is advisable to re-deploy those flows.
Adding multiple Webhook instances
There is an option to send answer payloads to multiple Webhook destinations. This is useful if you'd like to share your data across multiple endpoints, or have payloads that are sent at different submission frequencies go to different destinations.
To enable multiple destinations, first complete setup for an initial destination (Destination 1). Then, click the "+ Add destination" button. Up to 3 instances can be added.
Once you've finished configuring all instances of your Webhook integration, be sure to Save with the button in the top right corner.
If you have deployed flows previous to integrating with or updating your webhook, it is advisable to re-deploy those flows.