Installation with Composer 

Check whether you are already using the extension with:

composer show | grep reactions

This should either give you no result or something similar to:

typo3/cms-reactions       v12.4.11

If it is not installed yet, use the composer require command to install the extension:

composer require typo3/cms-reactions

The given version depends on the version of the TYPO3 Core you are using.

Installation without Composer 

In an installation without Composer, the extension is already shipped but might not be activated yet. Activate it as follows:

1. In the backend, navigate to the Admin Tools > Extensions module.
2. Click the Activate icon for the Reactions extension.

Navigate to the backend module 

To create a new reaction navigate to the System > Reactions backend module. If you call it the first time you will see the invitation to create a new reaction:

Create a new reaction 

Click on the button Create new reaction to add a new reaction.

The form provides the following general configuration fields:

Reaction Type

Select one of the available reaction types. The system extension comes with the Create database record.

Name

Give the reaction a meaningful name. The name is displayed on the overview page of the backend module.

Description

You can provide additional information to describe, for example, the purpose of this reaction in detail.

Identifier

Any reaction record is defined by a unique identifier. It is part of the TYPO3 URL when calling this reaction.

Secret

The secret is necessary to authorize the reaction from the outside. It can be re-created anytime, but will be visible only once (until the record is saved). Click on the "dices" button next to the form field to create a random secret. Store the secret somewhere safe.

The content of the "Additional configuration" section depends on the concrete reaction type. For the "Create database record" the following fields are available:

Table

Select one of the tables from the list. The corresponding fields displayed below change depending on the selected table. See also Extend list of tables on how to extend this list.

Storage PID

Select the page on which a new record should be stored.

Impersonate User

Select the user with the appropriate access rights that is allowed to add a record of this type. If in doubt, use the CLI user ("_cli_").

Fields

The available fields depend on the selected table.

Next to static field values, placeholders are supported, which can be used to dynamically set field values by resolving the incoming data from the webhook's payload. The syntax for those values is ${key}. The key can be a simple string or a path to a nested value like ${key.nested}.

For our example we select the Page Content table and populate the following fields:

We now save and close the form - our newly created reaction is now visible:

Call the reaction manually 

TYPO3 can now react on this reaction. Clicking on the Example button, the skeleton of a cURL request for use on the command line is showing up. We can adjust and run it on the console, using our placeholders as payload:

curl -X 'POST' \
    'https://example.com/typo3/reaction/a5cffc58-b69a-42f6-9866-f93ec1ad9dc5' \
      -d '{"header":"my header","text":"<p>my text</p>"}' \
      -H 'accept: application/json' \
      -H 'x-api-key: d9b230d615ac4ab4f6e0841bd4383fa15f222b6b'

When everything was okay and the record was created successfully, we receive a confirmation:

{"success":true}

If something went wrong, this is also visible, for example:

{"success":false,"error":"Invalid secret given"}

The content is now available on the configured page:

Extend list of tables 

By default, only a few tables can be selected for external creation in the create record reaction. In case you want to allow your own tables to be available in the reaction's table selection, add the table in a corresponding TCA override file:

if (\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::isLoaded('reactions')) {
    \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
        'sys_reaction',
        'table_name',
        [
            'label' => 'LLL:EXT:myext/Resources/Private/Language/locallang.xlf:tx_myextension_domain_model_mytable',
            'value' => 'tx_myextension_domain_model_mytable',
            'icon' => 'myextension-tx_myextension_domain_model_mytable-icon',
        ]
    );
}

In case your extension depends on EXT:reactions the isLoaded() check might be skipped. Please note that tables which configured adminOnly to true are not allowed.

Create the reaction type 

To create a custom reaction type, we add a class which implements the EXT:reactions/Classes/Reaction/ReactionInterface.php (GitHub):

<?php

declare(strict_types=1);

namespace T3docs\Examples\Reaction;

use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\StreamFactoryInterface;
use TYPO3\CMS\Core\Registry;
use TYPO3\CMS\Reactions\Model\ReactionInstruction;
use TYPO3\CMS\Reactions\Reaction\ReactionInterface;

class ExampleReactionType implements ReactionInterface
{
    private const REGISTRY_KEY = 'changed_ids';

    public function __construct(
        private readonly Registry $registry,
        private readonly ResponseFactoryInterface $responseFactory,
        private readonly StreamFactoryInterface $streamFactory,
    ) {}

    public static function getType(): string
    {
        return 'example-reaction-type';
    }

    public static function getDescription(): string
    {
        return 'Example reaction type';
    }

    public static function getIconIdentifier(): string
    {
        return 'tx_examples-dummy';
    }

    public function react(
        ServerRequestInterface $request,
        array $payload,
        ReactionInstruction $reaction
    ): ResponseInterface {
        $id = $payload['id'] ?? 0;
        if ($id <= 0) {
            $data = [
                'success' => false,
                'error' => 'id not given',
            ];

            return $this->jsonResponse($data, 400);
        }

        $this->updateRegistryEntry($id);

        return $this->jsonResponse(['success' => true]);
    }

    private function updateRegistryEntry(int $id): void
    {
        $ids = $this->registry->get('tx_examples', self::REGISTRY_KEY) ?? [];
        $ids[] = $id;
        $ids = array_unique($ids);
        $this->registry->set('tx_examples', self::REGISTRY_KEY, $ids);
    }

    private function jsonResponse(array $data, int $statusCode = 201): ResponseInterface
    {
        return $this->responseFactory
            ->createResponse($statusCode)
            ->withHeader('Content-Type', 'application/json')
            ->withBody($this->streamFactory->createStream(json_encode($data, JSON_THROW_ON_ERROR)));
    }
}

You can use constructor injection to inject necessary dependencies.

Add reaction type to select list in backend module 

In a next step we add the newly created reaction type to the list of reaction types in the backend:

<?php

defined('TYPO3') or die();

\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addTcaSelectItem(
    'sys_reaction',
    'reaction_type',
    [
        'label' => \T3docs\Examples\Reaction\ExampleReactionType::getDescription(),
        'value' => \T3docs\Examples\Reaction\ExampleReactionType::getType(),
        'icon' => \T3docs\Examples\Reaction\ExampleReactionType::getIconIdentifier(),
    ]
);

Now, our newly created type is displayed and can be selected: