Webhooks are used by developers to integrate Paperform form submissions into their own services. This is particularly useful if you would like to use forms within your own services or do something special or difficult with the submitted data.

Webhooks are only available on Pro and Agency plans. For non-technical teams, Direct Integrations, Zapier or Integromat are a more appropriate solution for most needs.

Adding a webhook

In the form editor, go to After Submissions → Integrations. Under the “Add Webhook” section, add the URL of your endpoint and click the “Add Webhook” button to add the webhook. That’s all it takes.

Testing webhooks

You can test a webhook at any time, by clicking the “TEST” button in the “Webhooks” section of After Submissions → Integrations. This will trigger the webhook with the latest submissions' data. Of course, you can always submit the form to test it as well.

Note that the form must have at least one submission to test webhooks.

Submission payload

Webhooks POST a JSON payload on submission to the webhook URL. The JSON payload looks like the following;

{  
  "data": [  
    {  
      "title": "question 1", // Title of question as defined  
      "description": "This is the second question",   
      "type": "address", // Question type  
      "key": "ba7ri", // Question pre-fill key (unique to form)  
      "custom_key": "address_1", // Custom pre-fill key (if set) 
      "value": "343 Tester Road, Snohomish, Washington, 98290, United States" // Submitted value for question
    },  
    {  
      "title": "question 2",  
      "description": "This is the second question",  
      "type": "text",  
      "key": "tgp8",  
      "custom_key": null,  
      "value": "Test 123"  
    }  
    // ...each question has its own object.  
  ],  
  "submission_id": "XXXXXXXXXXXXXXXXXXX", // Unique ID for submission.  
  "created_at": "2017-06-09 09:51:23", // Submission date  
  "ip_address": "192.168.10.1", // IP Address of submission  
  "charge": null // If a payment is made, payment information is given here  
}

The easiest way to see what your submission structure looks like is to use a service like https://requestinspector.com to create a webhook URL and send test data there.

The data array in detail

Each question is represented as a single object within the data array. Its object is present under all conditions. That is, even if the question is unanswered (e.g. an optional question) or the question is hidden (and it retains its answer when hidden or not), the object will still be present in the payload.

All of the properties of that object will also be present at all times, but may have varying values.

title — Title or, if blank, ""
description — Description or, if blank, null
type — Type
key — Automatically generated pre-fill key
custom_key — Custom key or, if not set, null
value — Value or, if no answer, null

Answer Piping in URL

The webhook URL also supports answer piping, which means that if you need to pass answers through as query string parameters, you can!

You can add answer piped values by either writing {{ key }} where "key" is the relevant question's pre-fill key, or by using the + menu to the right of the input.