Setting up a webhook for a form

If you're building a service or integrating with a third party and you need to receive each of the submissions for a particular form, you can set up a Webhook.

First, get the URL where the data should be sent, from your chosen third party service provider. Next, add a webhook to your form in Aiir, and paste in this URL.

Each time the form is submitted, the data will be sent to that URL in JSON as a POST request.

Where you source the URL and how the data is handled thereon is entirely up to you. Aiir is not able to provide technical support for setting up third party services, or parsing the data.

You can test webhooks using a tool like Webhook.site or RequestBin.com.

Here's an example of the JSON payload. The 'date_time' attribute is in ISO 8601 format.

{
    "event": "submission.create",
    "form": {
        "id": "123",
        "title": "My web form"
    },
    "submission": {
        "date_time": "2023-01-23T17:10:00+00:00",
        "fields": [
            {
                "name": "Name",
                "value": "Barry Scott",
                "type": "text_box",
                "personal_attribute": "name"
            },
            {
                "name": "Comment",
                "value": "Hello world",
                "type": "text_area"
            }            
        ]
    }
}

If you send a test, a property "test" with value true is included in the root of the payload.

Webhook Verification

A secret key will be generated when you set up a webhook on a form in Aiir.

This secret key is used to create a HMAC-SHA256 verification signature which is then sent within the headers of the webhook request.

You can use the signature to verify the integrity of the webhook message you have received.

You do this by using the secret key, encoding the payload of the webhook and comparing the generated value against the signature found within the "X-Aiir-Signature" header.

Below is a PHP based example on how to generate a HMAC-SHA256 signature from your webhook payload and compare it against the header value.

<?php

$encodedPayload = file_get_contents('php://input');
$secretKey = ''; // Fill in your webhooks secret key

$verifySignature = hash_hmac('sha256', $encodedPayload, $secretKey);

// PHP converts "X-Aiir-Signature" into "HTTP_X_AIIR_SIGNATURE"
$receivedSignature = $_SERVER['HTTP_X_AIIR_SIGNATURE'];

if ($receivedSignature === $verifySignature) {
    // webhook integrity confirmed.
    $decodedPayload = json_decode($encodedPayload)

    // process the data
} else {
    die('Webhook integrity compromised, do not process');
}