Form Submission Webhook

Webhooks allow you to send form submissions to a third-party application or service, and integrate FormSmarts with your site.

A webhook is an automated message (HTTP POST request) sent by FormSmarts to a predefined URL whenever a form is submitted. The code at this URL can then process the form response data contained in the message to do something useful. Webhook messages are structured JSON data, making them easy to use in any programming language.

Sample Webhook Message

We're going to use the form at https://f8s.co/lqh as a working example. Below is a sample message that would be sent to a cloud function or PHP script when the form is submitted. In the next section, we’ll demonstrate how to write simple code to process the webhook message.

{
   "api_id": "FSEVAPI",
   "api_version": "1",
   "api_date": "2012-04-30T16:11:04",
   "form_id": "lqh",
   "form_name": "File Upload Demo Form",
   "fs_ref_num": "6GZTWKU3HV7DAV1R8YE92L41B",
   "fields":
      [
         {
            "field_value": "Joe Bloggs",
            "field_name": "Full Name",
            "field_id": 1226194,
            "field_datatype": "name"
         },
         {
            "field_value": "bob@example.com",
            "field_name": "Email",
            "field_id": 1226205,
            "field_datatype": "email"
         },
         {
            "field_id": 1226216,
            "field_datatype": "attachment",
            "field_value": "",
            "field_name": "Upload Your Picture",
            "attachment_filename": "web-form-builder-heading.png",
            "attachment_url": "https://formsmarts.com/attachments/3vzs"
         },
         {
            "field_value": "This is a test comment.\r\nThank you\r\n\r\nBye,\r\nBob",
            "field_name": "Any Comments",
            "field_id": 1237447,
            "field_datatype": "text"
         }
      ]
}

Webhook messages are in JSON format with UTF-8 encoded text.

Webhook Example

The code below shows how to write a simple webhook callback in Python with the FormSmarts API & Webhook Client.

Note how we:

1. Verify that the callback was submitted by FormSmarts from the signature in the request headers with WebhookAuthenticator.verify_request()
2. Create a FormEntry object from the body of the request with FormEntry.create()
3. Get the picture upload field with self._entry.fields_by_type('upload')[0]
4. Download the picture and save it to a file with pic.download()

import formsmarts_api
import json
import config

logger = logging.getLogger()

class WebhookExample:

    def __init__(self, event):
        self._event = event
        self._api_auth = formsmarts_api.APIAuthenticator(
            config.FORMSMARTS_ACCOUNT_ID, config.FORMSMARTS_API_KEY
        )
        self._wh_auth = formsmarts_api.WebhookAuthenticator(config.FORMSMARTS_WEBHOOK_KEY)
        self._entry = None

    def process_entry(self):
        try:
            # Verify request is from FormSmarts
            if self._wh_auth.verify_request(self._event['headers']['authorization']):
                # Create a FormEntry object from the webhook message
                self._entry = formsmarts_api.FormEntry.create(
                    json.loads(self._event['body']),
                    api_authenticator=self._api_auth
                )
                self.save_picture()
            except formsmarts_api.APIRequestError as err:
                logger.warning(err)

    def save_picture(self):
        # Lookup up the first upload field and download a copy of the picture
        pic = self._entry.fields_by_type('upload')[0]
        pic.download(open(
            f'/Downloads/{self._entry.reference_number}-{pic.filename}', 'wb'
            ))

def lambda_handler(event, context):
    WebhookExample(event).process_entry()

Webhook Use Cases & Examples

Frequent uses of webhooks include:

• Sending notifications by SMS, to Microsoft Teams or Slack based on preset conditions
• Generating Word or PDF documents
• Saving the information submitted to a local database
• Subscribing/unsubscribing an email address from a mailing list

We’ve created a few comprehensive examples that you can use to develop your own webhooks:

• A property maintenance form that sends urgent requests to Slack
• A webhook to send an SMS confirmation when someone submits a form
• A simple online election application

Webhook Authentication

Before taking any actions based on the data received, you should always authenticate the webhook message to verify that the request was really sent by FormSmarts.

How to Verify a Webhook Message

Webhook callbacks are digitally signed with a JSON Web Token (JWT) in the Authorization header. You can easily verify a request with the Webhook Authenticator for Python, the Webhook Authenticator for Node.js, or a JWT library in your favorite language.

You can also use the FormSmarts API & Webhook Client, as in the code above.

FormSmarts webhook authentication relies on your Webhook Key. You will find your Webhook Key in the Security Settings of your account. Your key is secret, don't share it with anyone.

Webhook URL Registration

Once you've written the webhook code you want to run when a form is submitted, you need to register the callback URL¹ with the Form API. The Form API also allows you to view the current callback URL and cancel the webhook. You can call the API online with the API Console, curl or programmatically. This short video shows how to do this with the API Console.

form_id is the unique ID in the URL of the form, i.e. 196x for form https://formsmarts.com/form/196x.

Webhook Message Delivery & Retry Policy

When a form is submitted, FormSmarts attempts to deliver the HTTP callback to the form's Webhook URL immediately.

If the first delivery attempt fails (HTTP status code other than 200, 201, 202 or 204), we try to send it again:

• Three times in first hour
• Six more times within ten days

Form Response Metadata

api_id, api_version

The API used and its version.

api_date

The UTC date and time of the webhook callback in ISO 8601 format, e.g. 2012-04-30T16:11:04.

form_id

The unique ID of the online form on the FormSmarts platform that appears in the form URL, e.g. lqh for the form https://f8s.co/lqh.

form_name

The name of the form as set in the online form builder and appears in the subject of email notifications, e.g. File Upload Demo Form.

fs_ref_num

The FormSmarts reference number of the form response, e.g. 6GZTWKU3HV7DAV1R8YE92L41B

Form Response Payload

The fields list contains the form response payload. Each field appears in the list in the same order as the corresponding input field on the form, top to bottom. Four general properties are provided for each and every field: field_name, field_id, field_datatype and field_value. The notification payload may also include additional properties for some fields depending on the field's type. Payment and context information is also included if available.

Information Submitted by the Form User

field_name

The name of the field. Because the field name can be changed via the form builder, you should not assume it will be stable over time and therefore should not rely on it to identify a field in your programs. Use field_id instead.

field_id

A unique ID assigned by FormSmarts to each field. The field ID never changes and can be used to identify a field in your programs.

field_datatype

The datatype of a field defines the validation rules enforced by FormSmarts to ensure the quality of the information collected. You should always check the data type before taking an action that only applies to certain types. For example, assuming a field named Email Address, you should check the field's data type, not its name to ensure the field's value will contain a valid email address.

field_value

The value provided by the user, e.g. bob@example.com

Payment & Form Context

If the transaction includes a payment, amount due, or form submission context information, the respective property is included in the notification.

payment

If the form submission involves a payment, a payment property is included in the message with the following sub-properties: currency, amount, processor_name, transaction_id, processor_fee.

• currency: the ISO 4217 currency code of the payment
• amount: the total amount paid, including tax, shipping & handling
• processor_name: the name of the payment processor normalized in lowercase (e.g. paypal or stripe)
• transaction_id: the transaction ID assigned to this payment by the payment processor.
• processor_fee: the transaction fee charged by the payment processor.

amount_due

FormSmarts identifies amounts of money and item quantities even on forms that don't require the user to pay online. When a form response includes an Amount Due, the webhook message includes an amount_due property with the following attributes:

• amount: the total amount due
• currency: the ISO 4217 code of the currency

context

FormSmarts offers a way to differentiate between online forms submitted from different web pages or as part of separate campaigns with the form context parameter. If context information is available, the webhook notification will contain a context property with two sub-properties:

• label: the name of the context parameter
• value: the value of the context parameter

Webhook Web Callback HTTP Push API Integration API

---

1. Webhooks are available with all Business plans, subject to fair usage policy depending on your plan.