--- title: "Reactions (External Import endpoints)" manual: "External Import" version: "main" permalink: "https://docs.typo3.org/permalink/cobweb/external_import:user-reaction@main" source: "User/Reaction/Index.rst" rendered: "2026-10-10T09:03:14+00:00" --- # Reactions (External Import endpoints) {#user-reaction} When using TYPO3 12, External Import provides reactions, i.e. endpoints which can be called by any third-party software to push data to import or to delete imported data. Both reactions are defined in the same way. The expected payload is different, and this is explained further down. The "Import external data" reaction will import the data defined in the payload as per the usual External Import process, inserting, updating and deteting records by matching the incoming data set with the existing data set. However the import reaction could also be used to import a single record (for example, if it used as a webhook in a third-party application). In such a case, it is still easy to insert or update, but the deleting of records cannot be automated anymore. This is where the "Delete external data" reaction comes in. With it, one or more records can be targeted for deletion, using their external primary key to identify them. ## Defining the reaction {#user-reaction-reaction} A reaction must be defined using the "Reactions" module in the TYPO3 backend. There can be more than one External Import reaction depending on your needs. Having several reactions allows you to distribute secret keys to different people. ![Defining a reaction](../../Images/Reaction.png) Choosing a configuration is optional. If one is chosen, the reaction will only execute if the incoming configuration matches the selected configuration. This provides better safety, but is more restrictive. It is absolutely necessary to choose a BE user to impersonate, otherwise the data will not be stored. The easiest option is to choose the `_cli_` user but this may seem too encompassing. You can use another BE user or define a specific one, but make sure that it has the proper rights for writing to the table(s) targeted by the import. ## External Import configuration {#user-reaction-configuration} The External Import configuration does not need anything special to be used by a reaction. However if it is only ever used by reactions, then it does not need connector information and can thus be a [Non-synchronizable table](https://docs.typo3.org/permalink/cobweb/external_import:user-backend-module-non-synchronizable@main). > [!NOTE] > When using the "Delete external data" reaction, matched data will be deleted even > if the "delete" operation is disabled in the configuration > (using [disabledOperations](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-disabledoperations@main)). > It is assumed that you are meaning to delete anyway. ## Request payload {#user-reaction-payload} To call the endpoint and trigger the External Import reaction, you need to call the URI given by the reaction and pass it the secret key in the headers. The payload in the request body is comprised of the following information: - **table** The name of the table targeted by the reaction (not necessary when a configuration is explicitly defined). - **index** The index of the targeted External Import configuration (not necessary when a configuration is explicitly defined). - **group** Instead of defining a table and an index, it is also possible to define a group. In such a case, all configurations from the corresponding [groups](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-groups@main) will be executed in order of increasing priority. This is used only for the "Import external data" reaction. It is incompatible with a table and index definition. Defining both will trigger an error. It is not necessary when a group has been explicitly defined. - **data** The data to handle. For the "Import external data" reaction, this can be either a JSON array (for [array-type data](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-data@main)) or a (XML) string for [XML-type data](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-data@main)). For the "Delete external data" reaction, it must be a JSON array, with the item(s) to delete. The key for identifying the external data must be in a field called "external_id". Example: ```json { "table": "tx_externalimporttest_tag", "index": "api", "data": [ { "external_id": "miraculous" }, { "external_id": "rotten" } ] } ``` If the incoming data cannot match this structure (but is still a JSON array), use the [GetExternalKeyEvent](https://docs.typo3.org/permalink/cobweb/external_import:developer-events-get-external-key@main) event to extract the external key from the incoming data. If the incoming data does not match the above structure at all, you have to develop your own reaction. - **pid (optional)** If defined, this uid from the "pages" table will override the [pid property](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-pid@main) from the general configuration. This is not used by the "Delete external data" reaction. Here is how it could look like (example made with Postman): ![Request headers](../../Images/ReactionRequestHeaders.png) ![Request body](../../Images/ReactionRequestBody.png) ## The delete reaction {#user-reaction-delete-reaction} Since the "Delete external data" reaction is dedicated to deleting records, it is quite different from the other bits of code in External Import. As far as reaction payload is concerned, this has been discussed above. About the configuration, it is important to understand that most of the configuration is not used by the delete process. In fact the only properties that are used from the [general configuration](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca@main) are: - [referenceUid](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-reference-uid@main) to know in which field the external primary key is stored. - [enforcePid](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-enforcepid@main), which could be useful is a scenario where you would import the same records to different places in your TYPO3 installation, and thus have external primary keys which are unique only per pid. - [whereClause](https://docs.typo3.org/permalink/cobweb/external_import:administration-general-tca-properties-where-clause@main) > [!NOTE] > If the delete reaction tries to delete an already deleted record, the operation will > be silently successful. On the contrary, trying to delete a record which doesn't exist at all, > triggers an error. ## Reaction response {#user-reaction-response} The response contains a `success` entry with value `true` or `false`. If the `success` is `false`, the response will contain a `error` entry (string) for the delete reaction or an `errors` entry (array of strings) for the import reaction. These contain information about what went wrong. If the `success` is `true`, the response will contain a `message` entry (string) for the delete reaction or an `messages` entry (array of strings) for the import reaction. These contain information about the number of operations performed.