Formsort
Search…
Webhooks
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.

Posting Frequency

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.

Security

Formsort backend system will exclusively send webhook requests from the static IP 18.217.92.196.

Assured delivery

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:
1
{
2
...answers,
3
"variant_label": string,
4
"variant_uuid": string,
5
"finalized": boolean
6
}
Copied!
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:
  1. 1.
    All questions in the final step of the form have been answered, submitted, and the user has clicked Next.
  2. 2.
    All questions in any step with the Is Terminal option toggled on have been answered, submitted, and the user has clicked Next.
  3. 3.
    The user is redirected in the current tab.
  4. 4.
    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.

Testing webhooks

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.

Signing requests

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:
  1. 1.
    Hash it with SH256, encrypt it with signing key.
  2. 2.
    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.
  3. 3.
    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.
1
import base64
2
import hashlib
3
import hmac
4
5
6
def as_bytes(v):
7
return v.encode("utf8")
8
9
10
def hmac_sign(signing_key, original_request_body): # unmodified, a jsonified string
11
key = as_bytes(signing_key)
12
message = as_bytes(original_request_body)
13
return (
14
# Note:
15
# 1. for url safety, use - and _ characters instead of + and / respectively
16
# 2. remove the padding = signs at the end of the signature
17
base64.urlsafe_b64encode(
18
hmac.new(key, message, hashlib.sha256).digest())
19
.rstrip(b"=")
20
.decode("utf8")
21
)
Copied!

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.
Add your webhook URL
Add any other configuration options you require (covered in this chapter), and Save the configuration. 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.
Last modified 1mo ago