What are webhooks and how do I use them?

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.

This feature is exclusively available with specific pricing plans.

For non-technical teams, Direct Integrations, Zapier, or Make are more appropriate solutions for most needs.

Adding a webhook

1. In the form editor, navigate to After Submission → Integrations & Webhooks.
2. Click the "Webhooks" section near the bottom of the page to open the configuration options.
3. Click the "Add Webhook" button.
4. A modal will open - enter your webhook URL in the field provided.
5. Within the "Triggered On" dropdown menu, select whether you'd like this webhook to fire in response to a New Submission, or a Partial Submission.
6. Click the "Create" button to finalize your changes.

Testing webhooks

You may test a webhook at any time by clicking the "Test" button in the "Webhooks" section. This will trigger the webhook with the latest submission's data. You may also test your webhook by simply submitting your form.

The "test" button only works if your form has been submitted at least once.

Custom headers

Paperform webhooks support custom headers. These can be helpful for satisfying requirements on a hosted webhook platform, supplying additional information, and authentication - among other uses.

To get started, enable the "Custom headers" toggle when creating a new webhook. Simply click "+ Add Header" to add multiple additional headers.

Note: Custom Headers for webhooks do not support Answer Piping.

Submission payload

Webhooks POST a JSON payload on submission to the saved webhook URL(s).

Sample JSON payload

{  
  "data": [  
    {  
      "title": "question 1", // Title of question as defined  
      "description": "This is the first 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  
}

Comments in the above sample JSON are for illustration purposes only. Comments included in this manner are not valid JSON.

The simplest and quickest way to examine what your unique submission structure looks like is to use a service such as Request Inspector 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 (whether 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.

Possible values for the object

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.

Gotchas

• Partial Submission webhooks are only triggered when a given partial response has not been updated within the last 30 minutes, and has not been submitted yet.
• Only one webhook of each type will be dispatched for an individual submission record (partial or complete). This means multiple partial submission webhooks will not be triggered for the same response.