Getting Started

This page walks through one webhook: whenever a Car data object is updated, Pimcore sends a request to an external endpoint containing the object's name and description.

How a Webhook Works

An event such as pimcore.dataobject.postUpdate is caught by an event listener, which queues a message. A Symfony Messenger worker picks it up, hands it to the webhook processor for that event, and the processor checks every active webhook configuration: does the configuration listen to this event, does the element match the schema, and does it fall inside the configured workspace? If all three hold, the processor builds the payload and sends one HTTP request per subscriber.

Two consequences are worth remembering from the start:

• Nothing is delivered without a running worker. See Installation.
• A configuration that selects an event but has no matching schema definition sends nothing.

Prerequisites

• The bundle is installed and a worker consumes the pimcore_datahub_webhooks transport.
• Your user has the plugin_datahub_config and plugin_datahub_adapter_webhooks permissions.
• An endpoint that accepts HTTP requests and that Pimcore can reach.

1. Create a Webhook Configuration

In Pimcore Studio, open the main navigation and choose Automation & Integration > Data Hub Configuration. Add a new configuration and select the Webhooks adapter type.

The configuration opens with these tabs:

Tab	Purpose
General	Activate the configuration, set its log level, description and group.
Events & Schema	The events to listen to, and the payload sent to subscribers.
Workspaces	Restrict the configuration to parts of the element trees.
Subscribers	The endpoints that receive the requests, and their custom headers.
Logs	Application logger entries for this configuration.
Permissions	Which users and roles may read, update and delete this configuration.

2. Activate the Configuration

On the General tab, switch Active on. An inactive configuration is skipped, which is a convenient way to park a configuration without deleting it.

Set Log Level to Info while you build the webhook. It records every request, subscriber and HTTP status code in the Logs tab.

Reference: General.

3. Select the Event and the Payload

On the Events & Schema tab, select the event pimcore.dataobject.postUpdate.

Then configure the matching schema, otherwise no request is sent. Under Schema Definition Data Objects, add the class Car and open its Settings to choose the fields to send, for example name and description.

Reference: Events and Schema.

4. Restrict the Scope (Optional)

On the Workspaces tab, add a row for Objects with the path /Product Data/Cars and enable include. Only objects under that path then trigger the webhook.

Leave the tab empty to react to every element.

Reference: Workspaces.

5. Add a Subscriber

On the Subscribers tab, add the URL of your endpoint. Add custom headers if the endpoint needs them, for example an authorization header.

Use Test next to the input field to send a bodyless HTTP POST request to every subscriber and confirm Pimcore can reach them.

Reference: Subscribers.

6. Trigger and Verify

Save the configuration, then edit and save a Car object under /Product Data/Cars.

Once the worker processes the message, your endpoint receives an HTTP PUT request. The verb depends on the event: postAdd sends POST, postUpdate sends PUT, postDelete sends DELETE.

The body has a general section describing the event and a subject section with the fields you selected. Each selected field appears under its field name:

{
  "general": {
    "eventName": "pimcore.dataobject.postUpdate",
    "timestamp": 1690975273,
    "subjectType": "object",
    "versionOnly": false
  },
  "subject": {
    "id": 260,
    "path": "/Product Data/Cars/alfa romeo/1900",
    "name": "1900",
    "description": "<p>The Alfa Romeo 1900 is an automobile produced by Alfa Romeo from 1950 to 1959.</p>",
    "userModification": 25,
    "userModificationName": "admin",
    "published": false,
    "type": "Car"
  }
}

If nothing arrives, check the Logs tab first, then confirm a worker is running.

Reference: Request Structure and Logs.

Where to Go Next

• Send binary data such as images and thumbnails: Events and Schema.
• React to workflow transitions instead of element changes: Events and Schema.
• Build a payload the standard processors cannot produce: Extending.