Webhook

Listen for events on a form using a webhook.

What is a Webhook?

A webhook is an endpoint on your server that UseForms can call whenever an event occurs on a form with all the relevant information so that you can perform whatever processing you have setup for it.

A webhook allows you to react to events as soon as they happen.

Webhook Events

There are 5 events UseForms can send to your webhook.

• entry.created: This event is sent whenever a new response is submitted either using the web link or by an agent using the mobile app.

• entry.accepted: This event is sent whenever a response is accepted by an admin user.

• entry.rejected: This event is sent whenever a response is rejected by an admin user.

• entry.deleted: This event is sent whenever a response is deleted by an admin user.

• entry.batch_deleted: This event is sent when an action is taken by an admin user that causes multiple responses to be deleted. For example, when a form share is deleted.

Webhook Setup

To begin listening for submissions, you need to create a webhook endpoint on your server. The endpoint must be expecting a POST request and should return http status code 200 when the request is received successfully.

After creating the endpoint, you need to configure it on the Plugins page of your form. Input the full URL and select the configuration of entries you want to receive.

An https webhook URL is strongly recommended

When you create a webhook, you are given a webhook secret that you can use to verify that a request is sent by UseForms (more details on how to do this in the next section).

Your webhook secret should be treated just like your API key. Do not expose it or commit it to version control

The process to configure a webhook and retrieve the webhook verification key is shown below

Webhook configuration

Verifying Webhook Requests

All requests sent by UseForms will have a X-UseForms-Signature header which is a HMAC SHA512 signature of the request payload, signed using your webhook secret.

To verify that the request is sent by UseForms, you need to recreate the hmac signature using the sha512 algorithm and your webhook secret as the key then compare the result to the X-UseForms-Signature header.

Below is a sample code snippet that show how to do this using Node.js

const crypto = require('crypto');

app.post('/webhook', (req, res, next) => {
    const secret = 'YOUR_WEBHOOK_SECRET';
    const hash = crypto.createHmac("sha512", secret).update(Buffer.from(JSON.stringify(req.body), 'utf-8')).digest("base64");
    if (hash !== req.headers['X-UseForms-Signature']) {
        // This request is not from UseForms
        // Throw an error
    }
    
    // Request is from UseForms. Continue processing 
    const body = req.body;
});

Request Payload

All webhook requests will be in this format

{
   "event": "EVENT_TYPE",
   "data": ...
}

• event will contain one of the 5 webhook events

• data will contain the form response object or an array of objects in the case of the entry.batch_deleted event.