I. What is a Webhook Connection?

A webhook lets an external system - like a tracking device platform, a sensor portal, or any third-party tool - automatically send data to Gundi the moment something happens. Instead of Gundi checking for new data on a schedule, the external system does the work and "pushes" the data to you in real time.

Use a webhook connection when:

• Your data source supports sending HTTP requests to an external URL
• You need near real-time data delivery
• There's no pre-built Gundi integration available for your system

If you're not sure whether your system supports webhooks, check its documentation or ask your vendor.

II. Integration Process Summary

Before starting the integration process

1. Confirm with the device manufacturer or system developer that the device supports sending data to a Webhook.
2. Optional, but highly Recommended: Request a sample payload from the device manufacturer or system developer. If the sample is not available, contact our Support team to help you configure this integration.

Integration process in Gundi:

1. Create a Connection in Gundi. 
2. Set up your Webhook Schema.
3. Configure Field Mapping.

Integration process in Data Provider:

1. Configure base URL
2. Configure headers (Gundi Connection API Key and type)

III. Configuring Webhook in Gundi 

1. Navigate to the Webhook tab

Once your Webhook Connection has been created, go to the Webhook tab. This tab is only visible in Connections of type Webhook - if you don't see it, please ask our Support Team for clarification.

2. Set up your Webhook Schema.

The first step is telling Gundi what your incoming data looks like.

The easiest way to do this is to paste a sample payload (see “Prerequisites”) - a small example of the data your system sends. Gundi will automatically detect the structure and build the schema for you. You can also use the Schema Builder to define fields manually if you prefer.

What the schema is
The schema is a JSON Schema object that describes the structure of the data your external system will send to Gundi's webhook endpoint.

It defines:

• What fields are expected in the incoming payload
• The type of each field (string, number, boolean, object, array, etc.)
• Which fields are required vs. optional
• Optional constraints - formats (date-time, email, uuid), ranges (minimum/maximum), or allowed values (enum)

Why it's used
The schema serves two purposes:

1. It tells Gundi (and you) exactly what shape of data to expect from the sending system. It can be as vague or granular as you want/need. When Gundi receives a packet, it compares it against the schema and it rejects the packet if it doesn't match it.
2. The schema also powers the field mapping (transformation) builder. Once you define a schema, Gundi generates a realistic sample payload from it. This sample is what you can use to map incoming fields to Gundi's Observation or Event format when data arrives. 
    

Two ways to build it

The builder lets users either:

• Build it field-by-field using the visual UI (no JSON needed)
• Paste a sample JSON and have the schema auto-generated from it

3. Configure Field Mapping.

Once the schema is defined, the next configuration step is telling Gundi how to interpret the incoming data. 

3.1 Choose what type of object to create - an Observation (a location or sensor reading) or an Event (an alert or incident).

3.2 Use the Field Mapping UI to tell Gundi what each field means. For example, you might map a field called “y” in your payload to Gundi's “location.lat” field, and “device_id” to Gundi's “source” identifier. The visual builder guides you through this without needing to write any code. Once saved, Gundi will apply this transformation to every incoming message automatically.

3.3 After mapping all the key fields into the fields required by Gundi, and adding any optional data, use the Output Preview section to confirm that everything looks correct. You will see validation errors there if Gundi detects missing or incorrect field mappings.

3.4 When ready, click Save.

4. Share API Key

Share the Connection API key (found in the Connection “Provider” tab) with the party responsible for configuring the webhook in the data source.

IV. Configuring Webhook in Data Provider 

Follow these steps in your source system (e.g., ChirpStack, The Things Network, Digital Matter):

1. Create the webhook

• Name: Any label (e.g., gundi-webhook)
• Format: JSON (if prompted)

2. Set the endpoint

Base URL: 

https://hooks.gundiservice.org/webhooks

3. Add required headers

4. Save

Save the configuration in your source system.

IV. Requirements

• Every data packet must include a timestamp field, preferably in ISO 8601 format, representing when the event was recorded (for example, 2023-07-27T09:34-03:00 or 2023-07-27T09:34Z).
• Every data packet must include both a latitude field and a longitude field.
• Movement data must include a device ID or source ID field.

V. Integration Testing

• Trigger a sample event from your system (or wait for the next transmission).
• Confirm delivery:
  • Activity logs appears in Gundi
  • Data is received by the destination set up in your Gundi Connection