Using Webhooks with Lookups

Lookup files allow you to prepopulate fields on your forms. The data in the lookup file can come from external systems or spreadsheets. If the list of options need to change - for example an updated site or equipment list - you can update the underlying lookup file without rebuilding the form. This guide shows you have you can administer a lookup file automatically using data from an external system using Webhooks.

The lookups Webhook support the HTTP verbs GET, POST and DELETE to administer the data in a lookup file.

Note: A lookup file must already exist in your workgroup before you can administer it via Webhooks. A lookup file cannot be created via a Webhook.

Webhook Settings

To view the Webhook settings for an existing lookup file:

Log in to your workgroup and using the main menu on the left, click 'Forms'
Click 'Lookup Source'
Click 'Edit' next to the relevant lookup
At the top of the page click the 'Webhook Settings' option

The 'Webhook Settings' section will show you 3 pieces of information.

Webhook URL: This is the URL you need to use to administer the Lookup

Sample JSON Request: This will show you the JSON you need to supply to the Webhook. This can be different for each lookup as the data contained in each lookup can be significantly different from each other.

API Key: This is the API key needed to be supplied in the headers on the Webhook Request. Please see Introduction to Webhooks for further details.

Additionally, if you intend to update or remove existing lookup rows you need to specify which column uniquely identifies each row. If this is left blank, records will simply be appended to the file (causing duplicates) or in the case of deletions, these will be ignored.

GET Verb

Sending a GET request to the Webhook will return the Sample JSON request associated with the id.

GET Example

GET https://system.pro-forms.co.uk/webhooks/lookup.php?id=xyz

POST Verb

The POST verb should be used when adding/updating data in the lookup file. If updating existing row, a Primary Key field must be specified against the lookup otherwise the data is simply added to the file. The example below shows on one record being added. However multiple values are supported. If an array of data is passed then all rows will be added/updated. If you supply a column name in the JSON data that does not exist, a new column will be created in the lookup file.

POST Example

POST https://system.pro-forms.co.uk/webhooks/lookup.php?id=xyz

{
    "event": "record.created",
    "event_id": "evt_8f21c9a0",
    "timestamp": "2026-08-17T09:42:11Z",
    "data": {
            "customer": "XYZ Company",
            "contractor": "Abc Contractors",
            "contact": "usr_999",
            "tel_no": "0121 8745874",
            "contact_name": "Bob Smith",
            "contact_email": "bob.smith@xyzcompany.co.uk"
        }
}

POST Response Example

{
"status": "ok",
"lookup": "xyz",
"rows_added": 1,
"rows_updated": 0
}

DELETE Verb

The DELETE verb should be used when removing data in the lookup file. A Primary Key field must be specified against the lookup otherwise the data is simply ignored. The example below shows on one record being removed. However multiple values are supported. If an array of data is passed then all rows specified will be removed.

DELETE Example

POST https://system.pro-forms.co.uk/webhooks/lookup.php?id=xyz

{
    "event": "record.deleted",
    "event_id": "evt_8f21c9a0",
    "timestamp": "2026-08-17T09:42:11Z",
    "data": {
            "customer": "XYZ Company",
            "contractor": "Abc Contractors",
            "contact": "usr_999",
            "tel_no": "0121 8745874",
            "contact_name": "Bob Smith",
            "contact_email": "bob.smith@xyzcompany.co.uk"
        }
}

DELETE Response Example

POST https://system.pro-forms.co.uk/webhooks/lookup.php?id=xyz

{
 "status": "ok",
 "lookup": "xyz",
 "row_removed": 1
}

Introduction to Webhooks