Webhooks allow you to extend the FormSmarts platform1 and integrate it with your site and other services. Web hook notifications, also called callbacks, are HTTP POST requests sent to a pre-registered URL when a form has just been submitted. A script at this URL can then further process the information contained in the form response. Notifications are made of structured, JSON encoded data that is easy to process in any programming language.

Sample Notification Message

As a working example, we're going to use the form at http://f8s.co/lqh. Below is a sample of the notification message that is sent to the webhook (e.g. a PHP script on our site) each time the form is submitted. We demonstrate in the Webhook Example section how to write a simple PHP script to process notifications. Notifications 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":
"http://formsmarts.com/download/6GZTWKU3HV7DAV1R8YE92L41B-1Q1"
         }, 
         {
            "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 http://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.

Data TypeDescriptionExtra Properties
emailAn email address.
urlHTTP or HTTPS URL
phoneUniversal phone number
countryISO 3166 country code
dateUTC date in ISO 8601 format
nameLetters only
alphanumAlphanumeric
posintPositive integer
numberNumber
boolean'yes' or 'no'
optionOption of a drop-down list or radio-buttons
textlineA single line of text
textAny multi-line text
attachmentForm attachment (upload)attachment_filename, attachment_url

Important Security Notice: You should always ensure the data type of a field is email before sending an email message to an email address collected on a form.

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'});
}
?>

Web Hook Notification URL Registration

Once you've created a webhook script for a form, 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.

API Endpoint
https://formsmarts.com/api/v1/forms/form_id/webhooks/on_submit
HTTP MethodDescriptionParameters (in request body)
GETRetrieve current webhook URL of form form_id
PUTSet or update the webhook URLurl
DELETECancel webhook notification

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

Setting a webhook URL for your online form with the API console.
Setting a webhook URL with the API console.

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 secret API key. Verifying a request is much simplified by taking advantage of an OAuth library.

Complete Example with Authentication

Let's now revisit the example above and add message authentication.
Downloads
You can download a copy of all files for this example below. Don't forget to add your account number and secret API key as discussed next. 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 secret API key:

   // Paste your account number below (e.g. FSA-123456)
   private $formsmarts_account_num = "FSA-123456";
   // Paste your Secret API 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) {
  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.


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