Feature: #99629 - Webhooks - Outgoing webhooks for TYPO3

Triggers provided by the TYPO3 Core

The TYPO3 Core currently provides the following triggers for webhooks:

• Page Modification: Triggers when a page is created, updated or deleted
• File Added: Triggers when a file is added
• File Updated: Triggers when a file is updated
• File Removed: Triggers when a file is removed
• Login Error Occurred: Triggers when a login error occurred
• Redirect Was Hit: Triggers when a redirect has been hit

These triggers are meant as a first set of triggers that can be used to send webhooks, further triggers will be added in the future. In most projects however, it is likely that custom triggers are required.

Custom triggers

namespace TYPO3\CMS\Webhooks\Message;

use TYPO3\CMS\Core\Attribute\WebhookMessage;
use TYPO3\CMS\Core\Messaging\WebhookMessageInterface;
use TYPO3\CMS\Core\Resource\Event\AfterFolderAddedEvent;

#[WebhookMessage(
    identifier: 'typo3/folder-added',
    description: 'LLL:EXT:webhooks/Resources/Private/Language/locallang_db.xlf:sys_webhook.webhook_type.typo3-folder-added'
)]
final class FolderAddedMessage implements WebhookMessageInterface
{
    public function __construct(
        private readonly int $storageUid,
        private readonly string $identifier,
        private readonly string $publicUrl
    ) {
    }

    public static function createFromEvent(AfterFolderAddedEvent $event): self
    {
        $file = $event->getFile();
        return new self($file->getStorage()->getUid(), $file->getIdentifier(), $file->getPublicUrl());
    }

    public function jsonSerialize(): array
    {
        return [
            'storage' => $this->storageUid,
            'identifier' => $this->identifier,
            'url' => $this->publicUrl,
        ];
    }
}

public function __construct(
    protected readonly \Symfony\Component\Messenger\MessageBusInterface $bus
) {
}

public function processDatamap_afterDatabaseOperations($status, $table, $id, $fieldArray, DataHandler $dataHandler)
{
    if ($table !== 'pages') {
        return;
    }
    // ...
    $message = new PageModificationMessage(
            'new',
            $id,
            $fieldArray,
            $site->getIdentifier(),
            (string)$site->getRouter()->generateUri($id),
            $dataHandler->BE_USER,
    );
    // ...
    $this->bus->dispatch($message);
}

TYPO3\CMS\Webhooks\Message\FolderAddedMessage:
    tags:
      - name: 'core.webhook_message'
        identifier: 'typo3/folder-added'
        description: 'LLL:EXT:webhooks/Resources/Private/Language/locallang_db.xlf:sys_webhook.webhook_type.typo3-folder-added'

HTTP headers of every webhook

With every webhook request, the following HTTP headers are sent:

• Content-Type: application/json
• Webhook-Signature-Algo: sha256
• Webhook-Signature: <hash>

The hash is calculated with the secret of the webhook and the JSON encoded data of the request. The hash is created with the PHP function hash_hmac. See the following section about the hash calculation.

Hash calculation

The hash is calculated with the following PHP code:

$hash = hash_hmac('sha256', sprintf(
    '%s:%s',
    $identifier, // The identifier of the webhook (uuid)
    $body // The JSON encoded body of the request
), $secret); // The secret of the webhook

The hash is sent as HTTP header Webhook-Signature and should be used to validate that the request was sent from the TYPO3 instance and has not been manipulated. To verify this on the receiving end, build the hash with the same algorithm and secret and compare it with the hash that was sent with the request.

The hash is not meant to be used as a security mechanism, but as a way to verify that the request was sent from the TYPO3 instance.

Technical background and advanced usage

The webhook system is based on the Symfony Messenger component. The messages are simple PHP objects that implement an interface that denotes them as webhook messages.

That message is then dispatched to the Symfony Messenger bus. The TYPO3 Core provides a \TYPO3\CMS\Webhooks\MessageHandler\WebhookMessageHandler that is responsible for sending the webhook requests to the third-party system, if configured to do so. The handler looks up the webhook configuration and sends the request to the configured URL.

Messages are sent to the bus in any case. The handler is then responsible for checking whether or not an external request (webhook) should be sent.

If advanced request handling is necessary or a custom implementation should be used, a custom handler can be created that handles WebhookMessageInterface messages.