Webhook

Description

A webhook is a mechanism that allows GLPI to automatically send notifications to an external system (such as another software, an API, or a web service) when an event occurs in GLPI.

Examples: receive an alert (in a business messaging system like Mattermost) when a critical ticket is created, or synchronize the inventory with a billing system (if it provides an API to receive the webhook).

How does it work?

Configure a webhook in GLPI by specifying the triggering event, the related object, the destination URL, and the data to be sent.

When the event occurs, GLPI retrieves the information, prepares the data, and places the webhook in a queue. Just like GLPI’s regular Notifications, an automatic action then sends the HTTP request to the webhook URL. The destination system then receives the data and can process it.

Access the configuration

1. Go to Administration > Configuration > Webhooks

2. Click on + Add

Basic configuration form

• Name, Comments, Active, Category: the webhook is assigned a name, an optional comment, a category, and can be enabled or disabled.

• Entity: determines the scope of the webhook. The entity in which the webhook is created acts as the root; selecting child entities extends the webhook to events occurring in all sub-entities under this root.

• Itemtype: specifies the type of GLPI object that triggers the webhook (e.g., Ticket, User, Computer).

• Event: defines the action on the selected object type that will trigger the webhook (e.g., creation, update, deletion).

• Number of retries: sets how many times GLPI will attempt to resend the webhook if the initial HTTP request fails.

Target configuration

• URL: the destination address for the webhook. HTTPS is strongly recommended. Placeholder tags from the payload or header values can be used.

• HTTP method: the method used to send the webhook request;

  • POST: the webhook data is sent in the body of the HTTP request, typically to create a new resource or trigger an action on the destination system.

  • GET: the webhook data is sent in the URL as query parameters, it transmits information from GLPI to the destination system.

  • UPDATE: the webhook data is sent in the body to update an existing resource on the destination system.

  • PATCH: the webhook data is sent in the body to partially update an existing resource, modifying only the specified fields.

  • PUT: the webhook data is sent in the body to replace an existing resource entirely on the destination system.

• Save response body: stores the response returned by the destination system after the webhook call.

• Log in the item history: records the webhook execution and its response in the history of the triggering GLPI item.

Filters

By default, a webhook is triggered for all objects of the selected itemtype. Filters allow restricting the scope, for example to critical tickets only or to computers of a specific brand.

Filters are configured using GLPI’s standard search engine interface. Criteria can be defined and saved for reuse, and a Preview function allows displaying the potential results matching the filter before applying it to the webhook.

Security

Secret key

The Secret is a shared key between GLPI and the target system (transmit in a header), used to sign webhook requests sent by GLPI.

This secret is crucial for authentication, as it allows the target server to verify that the request genuinely originates from GLPI and not an imposter.

It also ensures integrity by enabling the target server to recalculate and compare a signature (sha256) generated from the request payload using the same secret; if the signatures match, the request is confirmed as authentic and unaltered.

Additionally, the secret enhances security by preventing attackers from forging valid requests or tampering with the data during transmission.

Expiration delay

The Expiration Delay defines a specific time window (for example, 10 hours) during which a webhook request remains valid.

This setting is essential for preventing replay attacks, as it ensures that even if a malicious actor intercepts a legitimate request, they cannot reuse it once the delay has expired.

Additionally, it enforces temporary validity, guaranteeing that only recent and relevant requests are processed, thereby minimizing the risk of outdated or fraudulent requests being accepted by the target system.

CRA Challenge

The CRA (Challenge-Response Authentication) is a security mechanism in which the target system issues a "challenge"—typically a random string or token—to GLPI, requiring GLPI to generate and return a valid response, often using a shared secret or private key.

This process is critical because it verifies the identity of the GLPI server, ensuring that only an authorized server with the correct credentials can successfully respond to the challenge.

CRA is particularly valuable in high-security environments, where confirming that the target server is communicating exclusively with the authentic GLPI instance is essential for maintaining trust and preventing unauthorized access.

OAuth Authentication

OAuth is an open authorization standard that enables GLPI to securely obtain an access token from a dedicated authorization server, which is then included in webhook requests to authenticate its identity.

To use OAuth, GLPI requires three key elements:

• the URL of the OAuth server’s token endpoint;

• a Client ID (a public identifier registered with the OAuth server);

• and a Client Secret (a confidential key shared only between GLPI and the OAuth server).

Summary of webhook security options

Payload editor

The payload of a GLPI webhook refers to the structured data sent as part of a request (typically in JSON format) to the target system.

This payload contains the essential details related to a specific event, enabling the receiving system to process or respond to the event accordingly.

When a webhook is created in GLPI, a default payload is automatically displayed and used.

This payload includes basic information about the item that triggered the webhook, as well as details about the event itself.

To fully customize the payload—such as adding specific fields, restructuring the data, or including additional context—one can disable the "Use default payload" option and define your own payload format.

Refreshing the page after clearing the editor and saving reverts the payload to its default state in edit mode.

When customizing the webhook payload, the payload editor includes an autocompletion feature that activates as soon as you type {{.

This feature helps you quickly insert dynamic variables related to the triggering item, such as {{item.id}}, {{item.name}}, or {{item.status.name}}, etc.

These variables are automatically replaced with the actual values from the item that triggered the webhook—such as a ticket, asset, or user—ensuring that the payload sent to external systems is always accurate and contextually relevant.

Example of a Webhook Payload for Mattermost

When configuring a webhook in GLPI to send notifications to Mattermost, you can customize the payload to match Mattermost's expected format. Here's an example of what the payload might look like:

{
  "text": "🚨 New critical ticket!",
  "attachments": [
    {
      "color": "danger",
      "title": "Ticket #{{ item.id }}",
      "text": "{{ item.name }}",
      "fields": [
        {
          "title": "Category",
          "value": "{{ item.category.name }}",
          "short": true
        },
        {
          "title": "Entity",
          "value": "{{ item.entity.completename }}",
          "short": true
        }
      ]
    }
  ]
}

When this payload is sent to Mattermost, it will be rendered as a rich message card, similar to this:

Custom headers

This configuration section allows users to define custom HTTP headers that will be included in the outgoing webhook request sent to the target system.

Custom headers can serve several key purposes:

• Authentication and Authorization: Headers like Authorization, API-Key, or custom tokens can be added to authenticate the webhook request with the target system;

• Content-Type Specification: You can explicitly define the format of the payload (e.g., Content-Type: application/json, Content-Type: application/xml) to ensure the target system correctly interprets the data;

• Metadata and Context: Custom headers can include additional metadata, such as request identifiers, timestamps, or environment-specific details, which help the target system process or route the request appropriately;

• Compatibility with APIs: Many third-party APIs require specific headers to function correctly. Custom headers allow GLPI webhooks to meet these requirements seamlessly.

Queries logs

The Queries logs tab lists all webhooks related to the current one: those already sent, pending to be sent, etc. It works the same way as the Queued Webhooks view, but is specific to the selected webhook.

Each entry displays its status code, and you can use the Force send button to manually trigger the delivery of a pending webhook. You can also click on the ID of a query log entry to view its detailed information.

Preview

The Preview tab allows you (1) to select an item available in GLPI (only items matching the configured itemtype of the webhook are listed). It displays both the (2) GLPI API data (the internal data source used by the webhook) and the (3) payload data that will be sent to the external system.

Queued Wehbooks

When an event occurs, GLPI does not send the webhook immediately. Instead, it is placed in a queue (glpi_queuedwebhooks). This approach prevents slowing down the user interface.

An Automatic action (queuedwebhook) automatically processes the queue:

• Retrieves pending webhooks

• Sends HTTP requests

• Handles errors and retries

• Updates webhook statuses

You can view the queue in Administration > Setup > Webhooks > Webhook Queue:

• See pending webhooks

• Manually force sending

• Check response status codes

• Resend failed webhooks

Another Automatic action (queuedwebhookclean) automatically cleans up the queue:

• Deletes old successfully sent webhooks (after X days)

• Deletes webhooks that have reached the maximum retry attempts