FormTab User Guide

Webhooks

Webhooks are a special type of Trigger that posts submission data to another web service for processing. There are two key components to a successful Webhook integration:

  1. Configuration of the Webhook trigger
  2. Setup/creation of the end point to receive and process the posted data

Webhook Configuration

Requires: A valid, public URL to post to. The trigger must be set up in your submissions area

Simple implementation

{
	"url":"https://test.webhook.co.nz/formtabwebhook"
}

Advanced JSON

Set "version": 2 to send the JSON in an advanced format.

{
	"url": "https://test.webhook.co.nz/formtabwebhook",
	"version": 2
}

TIP

Check out Advanced JSON Format for more details of this format.

Match On Parameter

A parameter to match on a form name is possible as follows:

{
	"url": "https://test.webhook.co.nz/formtabwebhook",
	"version": 2
	"matchon":"_name",
	"matchval":"Ground Survey",
 }



 
 

Receiving Webhook Data

It is up to you or your developer to implement a web-accessible end point to receive the Webhook data.

Posted Data

A POST of Content-Type application/json with contents of JSON data will be sent to the specified URL.

JSON Format

The data will be a list of key/value pairs where:

  • The Key is the field's label
  • The Value is the field's value
  • Each JSON object contains some base values derived from the Form Submission itself, such as _name and _username. The keys for these fields are all preceded with an underscore

Standard JSON Format

{
	"_reference": "70UW2AIW85",
	"_url": "https://www.formtabcentral.com/view/document-viewer/af234RqSDFOrUloBPs8Kf9FkqXK/html",
	"_id": "af234RqSDFOrUloBPs8Kf9FkqXK",
	"_device_created": "2015-02-11T11:21:21+0000",
	"_device_modified": "2015-02-11T11:28:21+0000",
	"_cloud_created": "2015-02-11T11:28:21+0000",
	"_cloud_modified": "2015-02-11T11:29:07+0000",
	"_username": "fred@dagg.com",
	"_name": "Test Form",
	"_description": "12345",
	"_status": "sent_to_community",
	"_user_ref": "1",
	"_tags": null,
	"Job No": "12345",
	"Comments":"Not a very big form to fill"
}

Advanced JSON Format

Advanced JSON (Version 2) output provides the data in a more structured format. It is useful if you require unique identifiers and arrays of table rows. Features of the Advanced JSON format:

  • Table fields contained within an array
  • UTC timestamped dates
  • Attachment filename information
  • URL and PDF links for optional use
  • Verification for API users
{
	"metadata": {
		"image": "997B8200-671B-D45A-D7D8-A508A0FDCB32.jpeg",
		"mode": "portrait",
		"name": "Sample Form",
		"description": "Sample Form",
		"created": "2017-06-15T14:53:08+12:00",
		"modified": "2017-06-15T14:53:22+12:00",
		"device_created": "2017-06-15T14:53:08+12:00",
		"device_modified": "2017-06-15T14:53:22+12:00",
		"author": "fred@formtabapp.com",
		"reference": "DHKKLNOXMQ",
		"public_token": "4wBu6l1cPms67uyexTogIvpU74D2fO2ipPpwW6qVeSAceXhRq",
		"user_ref": "19",
		"tags": null,
		"fingerprint": "92FD962CB8B25C85A1456762F8137A4E1506992595",
		"team_logo": "Wp8UAoVzoNwW9RFSZvU6meWqqZ3Wery3pNETIPCMTdB8IEANbYiLOQAGIZ0KwXCjPNp42xX3SxWGdGHbgzB",
		"team_name": "Demo Sandbox",
		"team_token": "W9RFSZvU6meWqqZ3Wery3pNETIPCMTdB8IEANbY"
	},
	"formdata": [
		{
			"uuid": "7e5adc4b-5f83-4705-8e88-db03c1808f98",
			"name": "Text",
			"type": "text",
			"label": "Text",
			"hidden": false,
			"value": "test"
		},
		{
			"uuid": "c1b0ab61-d372-491d-a415-e18749666b88",
			"name": "Example Segmented Field",
			"type": "segmented",
			"label": "Example Segmented Field",
			"hidden": false,
			"value": "Yes",
			"colour": "008000"
		}
	]
}

Response

Upon successful receipt and processing of the Webhook, you should return a valid HTTP 200 response.

In the event of an error, return a valid HTTP error code e.g. 404 Not Found, 400 Bad Request or 500 Internal Server Error. If you simply return an error message, this may get interpreted as a valid response.

Securing Your Webhook

If you are using Advanced JSON, you can validate incoming requests using your FormTab API Key.

The JSON object contains the following additional data:

  • Timestamp
  • Random token
  • Hash

The HMAC Hash generated with the following inputs:

  • Hash Function SHA256
  • Data Timestamp & Random token (concatenated)
  • Key Your API Key

For example, in PHP:

hash_hmac('sha256', $timestamp.$token, $api_key);

Callbacks

Webhooks can be configured to include a set of callback URLs to assist with automated workflow. This makes it easy for you to hook up Zapier workflows, or create your own custom workflows without having to use the API.

To include callback URLs you must include a json parameter in your Webhook Configuration:

{
	...
	"include_callback_urls": true
}

The Webhook data will contain multiple Callback URLs, each for a different function. These are detailed below.

For security purposes, each individual callback URL may only be called once, however multiple callback URLs can be called. For example, you may wish to call the Change Status callback before calling the Escalate callback.

(Note: It is not recommended to call both Reject and Escalate in response to the Webhook as this will result in user confusion and data duplication issues).

Receipt Callback URL

The Receipt URL provides functionality to provide FormTab with a confirmation that the Webhook has been received.

No parameters required.

Reject Callback URL

The Reject URL, if called, will send the author a request to revise the form (and will send the form back to their FormTab inbox).

No parameters required. Do not call Escalate and Reject callback URLs for the same Webhook process.

Escalate Callback URL

Escalate enables forwarding the form on to a different team member.

  • The user will be alerted to the escalation
  • The form will be sent to their FormTab inbox

Do not call Escalate and Reject callback URLs for the same Webhook process.

Required parameter:

  • username
    string
    Username of the person the form should be sent to. They must be an active member of the same Team

Change Status Callback URL

The Change Status URL, if called, will update the custom status of the Submission.

Required parameter:

  • status
    string
    Custom Team Status, if defined.

Review

Review sends a link to one or more team member/s or group of team members view the submission in the FormTabCentral.com Submissions area.

Administrator or Reporter level team members will be required to login, before they can view the submission. This will provide them access to access additional workflow functionality. Regular team members will receive a standard public view-only link to the submission.

Required parameters:

  • group
    string
    One of the following User Levels administrators, reporters or members

OR

  • username
    string
    Single email address, or comma separated list of email addresses. The email addresses must belong to active members of the Team
Last Updated: