Webhook (Reaction)

TYPO3 v12 adds the possibility to receive webhooks and react to them with reactions using the typo3/cms-reactions core extension. When it is installed, the Interest extension can use a webhook as a wrapper for a REST request.

Differences between a webhook and REST request

The implementation is similar to a normal REST request, except:

The entry point is always the reaction extension's entry point: /typo3/reaction/{reactionId}
Backend user authentication is handled by the reactions extension.
The HTTP method of a reaction request must always be POST, so you must instead provide the action in the JSON array key method (POST, PUT, PATCH, or DELETE).
table, remoteId, language, and workspace can only be supplied in the JSON array.

Create an Interest reaction

To create a new reaction navigate to the System > Reactions backend module. Then click on the button Create new reaction to add a new reaction.

In the form, select the reaction type "Interest operation (create, update, or delete)" and fill in the other general configuration fields.

Remember to hold on to the content of the Secret field. The secret is necessary to authorize the reaction from the outside. It can be recreated 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.

When you save and close the form, the reaction will be visible in the list of reactions.

Request URL

By clicking on the Example button in the list of reactions, you'll see skeleton of a cURL request for use on the command. You can adjust and run it in the console, using our placeholders as payload:

curl -X 'POST' \
    'https://example.com/typo3/reaction/a5cffc58-b69a-42f6-9866-f93ec1ad9dc5' \
      -d '{"method":"PATCH","table":"pages","remoteId":"testPage","data":{"title":"Test Name","pid":"siteRootPage"}}' \
      -H 'accept: application/json' \
      -H 'x-api-key: d9b230d615ac4ab4f6e0841bd4383fa15f222b6b'

Request data

Your payload data should always contain at least contain the key method.

Specifying the HTTP request header

Because webhook-based requests always use the POST method, it must be overridden in your data. This means

method refers to the HTTP request method that would otherwise have been used by the REST request. The available values are POST, PUT, PATCH, and DELETE. More information in the REST API section on HTTP Methods.

Example request data

The request data can be formatted for both single and batch operations. A single-record request could look like this:

{
   "method": "PATCH",
   "table": "pages",
   "remoteId": "testPage",
   "data": {
      "title": "Test Name",
      "pid":"siteRootPage"
   }
}

A batch request could look like this:

{
   "method": "POST",
   "data": {
      "pages": {
         "Page-1": {
            "title": "My first page",
         },
         "Page-2": {
            "title": "My second page",
         }
      },
      "tt_content": {
         "Content-1": {
            "heading": "Welcome to the first page",
            "pid": "Page-1"
         },
         "Content-2": {
            "heading": "Welcome to the second page",
            "pid": "Page-2"
         }
      }
   }
}

You can read more about creating batch requests in the REST API section on Batch requests.