> For the complete documentation index, see [llms.txt](https://docs.globalalerting.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globalalerting.com/web-api/webhooks.md).

# Webhooks

The Webhooks feature allows third-party systems to be notified every time a specified action occurs. Webhooks are currently supported for Devices, Users, Tenants, MO Messages and Event Notifications.

Each data item is sent individually soon after the action occurs on GAP.  The item is serialized using JSON and includes an indicator of the item type, the action taken, and the item itself.

## Authentication

You can choose either basic authentication or no authentication.

See [Configuring Webhooks](/administration/integrations/configuring-webhooks.md) for information on how to set up a webhook.

## Retry

A retry mechanism is in place that will repeat the call several times until success HTTP status code is received.

## Payload

A webhook payload consists of ItemType, Action and Item properties.

ItemType specifies the entity type that triggered the webhook.  Possible values are Device, User, Tenant, MoMessage and EventNotification.

Action specifies what triggered the webhook.  Possible values are Create, Edit, Delete and Trigger.

{% code lineNumbers="true" %}

```json
{
    "ItemType": "Device",
    "Action": "Create",
    "Item": {
    …
    }
}
```

{% endcode %}

The Item property contains the record that triggered the webhook.  This property contains the same JSON as you would expect to receive had a GET request been made to the Web API for the entity type specified in the ItemType property.

For example, if you had just created a device called "Test Device #1", you would receive the following payload:

{% code lineNumbers="true" %}

```json
{
    "ItemType": "Device",
    "Action": "Create",
    "Item": {
        "TenantCode": "1234",
        "DeviceId": "123456789",
        "DeviceType": "Generic",
        "FriendlyName": "Test Device #1",
        "DeviceStatus": "Active",
        "ProvisioningStatus": "Provisioned",
        "DateAdded": "2025-02-18T05:16:05.700109Z",
        "CheckInScheduleOverdue": 0,
        "EnableEmailDelivery": false,
        "EnableSmsReplies": false,
        "IsMonitored": false,
        "MonitoringOverdue": 0,
        "EmergencyState": 0,
        "Properties": {
            "MapIcon": "fa-location-arrow",
            "MarkerColor": "blue",
            "CreatedBy": john.smith@globalalerting.com
        },
        "Timestamp": "2025-02-18T05:16:05.7116537Z",
        "ETag": "W/\"datetime'2025-02-18T05%3A16%3A05.7116537Z'\""
    }
}
```

{% endcode %}

See the following endpoints for more information on the data included in the Item property:

* [Devices](/web-api/devices.md#get-v2-tenantvarcode-devices-deviceid)
* [MO Messages](/web-api/mo-messages.md#get-v2-tenantvarcode-devices-deviceid-momessages-messageid)
* [Tenants](/web-api/tenants.md#get-v2-tenantvarcode)
* [Users](/web-api/users.md#get-v2-tenantvarcode-users-userid)

### Event Notifications

Event Notification webhook payloads differ from the response to a GET request on the Event Notifications endpoints.

Note the "Trigger" value of the Action property, indicating that the event notification referenced by the NotificationId property has fired.

An example is shown below:

{% code lineNumbers="true" %}

```json
{
    "ItemType": "EventNotification",
    "Action": "Trigger",
    "Item": {
        "DeviceId": "1234567890",
        "TenantVarCode": "1234",
        "NotificationId": "fca3aa88-934d-4d1e-a239-236af166c4ed",
        "NotificationName": "MyEventNotification",
        "NotificationText": null,
        "NotificationSeverity": "0",
        "NotificationOrigin": "Device",
        "Time": "2026-05-21 22:19:43Z",
        "Reason": "message type equals CheckIn",
        "MoMessageId": null,
        "MoMessageType": "CheckIn",
        "MoMessageText": "CheckIn",
        "MoMessageEmergencyState": "NotSpecified",
        "MoMessageSentFromDevice": "2026-05-21 22:19:42Z"
    }
}
```

{% endcode %}