Skip to main content
Version: 2024.4

Create a Webhook Processor

Extending or replacing existing processors is as easy as it gets.

General​

There are two different EventListener registered in services.yml. Each one of them listens to a specific set of events. If one of these events is triggered, the EventListener calls the corresponding WebhookProcessor, which is responsible for executing the webhook.

Event Listeners​

ElementEventListener​

Handles all events based on elements, e.g. postAdd and postUpdate events for Data Objects, Documents and Assets.

Pimcore\Bundle\DataHubWebhooksBundle\EventListener\ElementEventListener:
    tags:
        - { name: kernel.event_listener, event: pimcore.dataobject.postAdd, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.dataobject.postUpdate, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.dataobject.postUpdateFailure, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.asset.postAdd, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.asset.postUpdate, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.asset.postUpdateFailure, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.document.postAdd, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.document.postUpdate, method: processEvent }
        - { name: kernel.event_listener, event: pimcore.document.postUpdateFailure, method: processEvent }
        ...

WorkflowEventListener​

Handles all events based on workflows, e.g. workflow.entered event.

Pimcore\Bundle\DataHubWebhooksBundle\EventListener\WorkflowEventListener:
    tags:
        - { name: kernel.event_listener, event: workflow.entered, method: processEvent }
        - { name: kernel.event_listener, event: workflow.completed, method: processEvent }

Webhook Processor​

The webhook processor is responsible for gathering the payload data and sending the request to all subscribers.

Every WebhookProcessor available needs to be based on the WebhookProcessorInterface.

  • AbstractWebhookProcessor: Provides basic functionalities that are shared between all processors.
  • AssetWebhookProcessor: Provides functionalities specific to Assets, such as adding binary data to requests.
  • DataObjectWebhookProcessor: Provides functionalities specific to Data Objects, such as including unpublished objects.
  • DocumentWebhookProcessor: Provides functionalities specific to Documents, such as userModification.
  • WorkflowWebhookProcessor: Provides functionalities specific to workflows, such as transitions and marking.
tip

If you need more configuration options and want to fully customize the payload sent to your subscribers, you can also create your own webhook processor. It must implement the WebhookProcessorInterface.

Each event that is listened to needs a separate entry in services.yml connecting the processor to the event:

pimcore.webhooks.processor.dataobject.postAdd:
    class: Pimcore\Bundle\DataHubWebhooksBundle\Processors\DataObjectWebhookProcessor
    arguments:
        $httpMethod: 'POST'
    tags:
        - { name: pimcore.datahub.webhooks_event, event: pimcore.dataobject.postAdd}

pimcore.webhooks.processor.dataobject.postUpdate:
    class: Pimcore\Bundle\DataHubWebhooksBundle\Processors\DataObjectWebhookProcessor
    arguments:
        $httpMethod: 'PUT'
    tags:
        - { name: pimcore.datahub.webhooks_event, event: pimcore.dataobject.postUpdate}

pimcore.webhooks.processor.dataobject.postUpdateFailure:
    class: Pimcore\Bundle\DataHubWebhooksBundle\Processors\DataObjectWebhookProcessor
    arguments:
        $httpMethod: 'PUT'
    tags:
        - { name: pimcore.datahub.webhooks_event, event: pimcore.dataobject.postUpdateFailure}

pimcore.webhooks.processor.dataobject.postDelete:
    class: Pimcore\Bundle\DataHubWebhooksBundle\Processors\DataObjectWebhookProcessor
    arguments:
        $httpMethod: 'DELETE'
    tags:
        - { name: pimcore.datahub.webhooks_event, event: pimcore.dataobject.postDelete}

To extend the WebhookProcessor one can create a new class that extends the AbstractWebhookProcessor and implements the WebhookProcessorInterface. Then the new class can be registered in the services.yml file (as described above).

Following methods can be overridden to extend the functionality to custom needs

  • AbstractWebhookProcessor::mustSkipWebhookRequest()
    • Purpose: Skip sending request to subscriber if necessary.
    • Default behaviour when not overridden: returns false
  • AbstractWebhookProcessor::updateRequestBodyForSubscriber()
    • Purpose: update request body for specific subscriber
    • Default behaviour when not overridden: return the default request body/payload (which is one of the parameters of the method)
  • AbstractWebhookProcessor::getAdditionalOptionsForSubscriber()
    • Purpose: Add additional options to the request for specific subscriber, e.g. HTTP headers which might be necessary for authentication.
    • Default behaviour when not overridden: return empty array
  • AbstractWebhookProcessor::handleResponse()
    • Purpose: Handle the response from the subscriber / update element etc. possible.
    • Default behaviour when not overridden: do nothing

WebhookProcessorInterface​

The three following methods need to be used in your php file for implementing the WebhookProcessorInterface:

  • WebhookProcessorInterface::fire() - responsible for executing the actual webhook based on the configuration in the Datahub.

  • WebhookProcessorInterface::matchByEvent() - checks if the current event can be handled by the WebhookProcessor.

  • WebhookProcessorInterface::matchBySchema() - checks if the event and the corresponding object matches the schema in the Datahub configuration (workspaces, types, ...).