Webhook

A webhook allows you to deliver form submissions to another application or service and integrate FormSmarts with your site.

A web hook notification, also called web callback, is an automated message (HTTP POST request) FormSmarts sends in real-time to a URL you've configured when a form is submitted. Code at this URL can then further process the information in the form response. Webhook messages are structured JSON data that is easy to use in any programming language.

Sample Webhook Message

As a working example, we're going to use the form at https://f8s.co/lqh. Below is a sample of the notification message that is sent to the webhook (e.g. a PHP script on your site) each time the form is submitted. We demonstrate in the Webhook Example section how to write a simple PHP script to process webhook messages. Messages are in JSON format with UTF-8 encoded text.

{
   "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"
         }
      ]
}

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 will also be 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 data type 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 or form context information, the respective property will be included in the notification.

payment

If the form submission involves a payment, a payment property will be incuded in the message with the following sub-properties: currency, amount, processor_name, processor_txn_id.

• 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)
• processor_txn_id: the transaction ID assigned to this payment by the payment processor.

Note: Webhook notifications only include payments using FormSmarts' advanced PayPal integration.

form_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 variable. If context information is available, the webhook notification will contain a form_context property with two sub-properties:

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

Webhook Example in PHP

<?php
// parse raw POST data
$form = json_decode(file_get_contents("php://input"));

print($form->{'api_version'});
print($form->{'form_name'});
print($form->{'fs_ref_num'});
print($form->{'api_date'});

// get the list of fields in the order they appear on the form
$fields = $form->{'fields'};

// iterate over fields
foreach($fields as $field) {
  print($field->{'field_name'});
  print($field->{'field_value'});
  // form attachments have additional properties (but field_value is empty)
  if($field->{'field_datatype'} == 'attachment') print($field->{'attachment_url'});
}

// print data type of first field
print($fields[0]->{'field_datatype'});

// print payment information, if applicable
if(array_key_exists('payment', $form)) {
  $payment = $form->{'payment'};
  print($payment->{'currency'});
  print($payment->{'amount'});
  print($payment->{'processor_name'});
  print($payment->{'processor_txn_id'});
}

// print information passed to the context parameter, if available
if(array_key_exists('form_context', $form)) {
  print($form->{'form_context'}->{'label'});
  print($form->{'form_context'}->{'value'});
}
?>

Message Authentication

Before taking any actions based on the data received, you should authenticate the notification message. Message authentication allows you to verify that a request genuinely originates from FormSmarts and hasn't been modified. You should always authenticate a notification message whenever a form submission includes a payment or before sending an email based on the data received.

How to Authenticate a Notification

All callbacks are digitally signed with the standard OAuth 1.0 authentication protocol. FormSmarts's OAuth 1.0 implementation relies on two tokens for authentication: your FormSmarts account number and your Webhook Key. Verifying a request is much simplified by taking advantage of the Webhook Authenticator for Python, the Webhook Authenticator for Node.JS, the PHP code given below, or an OAuth library.

Complete Example with Authentication

Let's now revisit the example above and add message authentication. There are more examples in the Webhook Examples side box.

Downloads

You can download a copy of all files for this example below. Don't forget to add your account number and Webhook Key as discussed next.

• FormSmarts_Webhook_Example.php
• FormSmarts_OAuth_Server.php
• FormSmarts_OAuth.php
• FormSmarts.php

The Oauth implementation in FormSmarts_OAuth.php and FormSmarts_OAuth_Server.php is a slightly simplified version of this library.

The Code

First edit FormSmarts_OAuth_Server.php and paste your FormSmarts account number and Webhook Key:

   // Paste your account number below (e.g. FSA-123456)
   private $formsmarts_account_num = "FSA-123456";
   // Paste your Webhook Key below
   private $formsmarts_secret_key = "m9DwEcCqDZznQ5UI10AqciRWybRkdNgwB1qEhV8h93KTEcO846jqt1N9pSeU4OkN";

The callback script (FormSmarts_Webhook_Example.php) now becomes:

<?php

require_once("FormSmarts_OAuth.php");
require_once("FormSmarts_OAuth_Server.php");
require_once("FormSmarts.php");

// Log file for demonstration & debugging
$fh = fopen('/tmp/formsmarts_webhook_call.log', 'a');

// Decode JSON

$form = json_decode(file_get_contents("php://input"));

// Normalize response data for OAuth

$norm = new FormSmartsParameterNormalizer();
$norm_params = $norm->normalize($form);

// Authenticate request with OAuth 1.0

$test_server = new TestOAuthServer(new MockOAuthDataStore());
$hmac_method = new OAuthSignatureMethod_HMAC_SHA1();
$test_server->add_signature_method($hmac_method);

try {
  $req = OAuthRequest::from_request(Null, Null, $parameters=$norm_params);
  // Will throw an exception if the signature is not verified
  list($consumer, $token) = $test_server->verify_request($req);
} catch (OAuthException $e) {
  header("HTTP/1.1 401 Unauthorized");
  fwrite($fh, $e->getMessage() . "\n<hr />\n");
  fwrite($fh, print_r($req, TRUE));
  die();
}

// We've established the request is really originating from FormSmarts.
// We can now start to do something useful...
// Note: Do NOT insert your own code before this line!

fwrite($fh, $form->{'api_version'});
fwrite($fh, $form->{'form_name'});
fwrite($fh, $form->{'fs_ref_num'});
fwrite($fh, $form->{'api_date'});

$fields = $form->{'fields'};

// iterate over all fields

foreach($fields as $field) {
  fwrite($fh, $field->{'field_name'});
  fwrite($fh, $field->{'field_value'});
  if($field->{'field_datatype'} == 'attachment') {
    fwrite($fh, $field->{'attachment_url'});
    fwrite($fh, $field->{'attachment_filename'});
  }
}

// print value ID of first field

fwrite($fh, $fields[2]->{'field_datatype'});


// print payment information, if applicable
if(array_key_exists('payment', $form)) {
  $payment = $form->{'payment'};
  fwrite($fh, $payment->{'currency'});
  fwrite($fh, $payment->{'amount'});
  fwrite($fh, $payment->{'processor_name'});
  fwrite($fh, $payment->{'processor_txn_id'});
}


// print context info, if available.

if(array_key_exists('form_context', $form)) {
fwrite($fh, $form->{'form_context'}->{'label'});
fwrite($fh, $form->{'form_context'}->{'value'});
}

fclose($fh);
?>

Example in PHP on Windows/IIS

We found that it was simpler to write webhooks in PHP even on Windows/IIS (rather than in ASP/ASP.net) because it appears there is no consistent way to parse JSON in the different flavors of ASP. The callback scripts presented above will work with PHP on Windows after minor modifications (modified script below). If your Windows server doesn't have PHP (version >= 5.2.0), you can download it from Microsoft's site.

• FormSmarts_Webhook_Example_Windows_IIS.php

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¹ via the FormSmarts Web API. The API also allows you to view the current notification URL or cancel the webhook. You can call the API 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 endpoint in real-time.

If the first delivery attempt fails (HTTP status code other than 200), we try to deliver the event-notification again three times in the following hour, then six more times within ten days.

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.