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.

You’ve reached our technical documentation. You may wish to visit our features page on webhooks.

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.

• Abandoned: 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:

{
  ...answers,
  "flow_label": string,
  "variant_label": string,
  "variant_uuid": string,
  "finalized": boolean,
  "created_at": string
}

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. All questions in the final step of the form have been answered, submitted, and the user has clicked Next.

2. User arrives at a step with the Is finalizing? option toggled on.

3. The user is redirected in the current tab.

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.

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.