# Synchronization endpoints Synchronization endpoints have a very similar role to message handlers in a message queue system. They receive the event(message) with data and react to its payload. There are several endpoints corresponding to events in the Manifest configuration. {% hint style="info" %} Each endpoint receives an appropriate `X-APP-TOKEN` HTTP header with JWT that allows [authentication](/apps2/detailed-reference/authentication.md#authentication-of-the-incoming-request) of the caller. {% endhint %} JWT for all synchronization endpoint requests is extended with an extra context claim `synchronization_id`. This claim is a UUID and allows identification of the synchronization process. Every endpoint should respond with a 2xx HTTP code to be treated as a success. ## Synchronization endpoints All the endpoints follow the semantic `[PUT] /consume/{event}`. {% hint style="info" %} `synchronization.events` contains an array of detailed payloads containing actual changes - [the full list can be found here](/apps2/detailed-reference/synchronization/synchronization-events.md). Those events allow retrieving information about what has changed and reacting to that change. This field for DELETED events is always an empty array. {% endhint %} #### /consume/attribute\_created subscribed event: [attribute\_created](/apps2/detailed-reference/manifest.md#attribute_created) example payload: ```json { "name": "attribute_created", "resource_id": { "id": "Attribute_code", "type": "attribute_code" }, "synchronization": { "resource_customs": null, "events": [] } } ``` #### /consume/attribute\_updated subscribed event: [attribute\_updated](/apps2/detailed-reference/manifest.md#attribute_updated) #### /consume/attribute\_deleted subscribed event: [attribute\_deleted](/apps2/detailed-reference/manifest.md#attribute_deleted) example payload: ```json { "name": "attribute_deleted", "resource_id": { "id": "Attribute_code", "type": "attribute_code" }, "synchronization": { "resource_customs": {"your": "custom"}, "events": [] } } ``` #### /consume/category\_created subscribed event: [category\_created](/apps2/detailed-reference/manifest.md#category_created) example payload: ```json { "name": "category_created", "resource_id": { "id": "Category_code", "type": "category_code" }, "synchronization": { "resource_customs": null, "events": [] } } ``` #### /consume/category\_updated subscribed event: [category\_updated](/apps2/detailed-reference/manifest.md#category_updated) example payload: ```json { "name": "category_updated", "resource_id": { "id": "Category_code", "type": "category_code" }, "synchronization": { "resource_customs": {"your": "custom"}, "events": [] } } ``` #### /consume/category\_deleted subscribed event: [category\_deleted](/apps2/detailed-reference/manifest.md#category_deleted) example payload: ```json { "name": "category_deleted", "resource_id": { "id": "Category_code", "type": "category_code" }, "synchronization": { "resource_customs": {"your": "custom"}, "events": [] } } ``` #### /consume/product\_created subscribed event: [product\_created](/apps2/detailed-reference/manifest.md#product_created) example payload: ```json { "name": "product_created", "resource_id": { "id": "Product SKU", "type": "sku" }, "synchronization": { "resource_customs": null, "events": [] } } ``` #### /consume/product\_updated subscribed event: [product\_updated](/apps2/detailed-reference/manifest.md#product_updated) example payload: ```json { "name": "product_updated", "resource_id": { "id": "Product SKU", "type": "sku" }, "synchronization": { "resource_customs": {"your": "custom"}, "events": [] } } ``` #### /consume/product\_deleted subscribed event: [product\_deleted](/apps2/detailed-reference/manifest.md#product_deleted) example payload: ```json { "name": "product_updated", "resource_id": { "id": "Product SKU", "type": "sku" }, "synchronization": { "resource_customs": {"your": "custom"}, "events": [] } } ``` #### /consume/synchronization\_started subscribed event: [synchronization\_started](/apps2/detailed-reference/manifest.md#synchronization_started) example payload: ```json { "name": "synchronization_started" } ``` #### /consume/synchronization\_ended subscribed event: [synchronization\_ended](/apps2/detailed-reference/manifest.md#synchronization_ended) example payload: ```json { "name": "synchronization_started" } ``` ### Resource customs In the above examples, you might have noticed the `resource_customs` field. This mechanic allows small pieces of information such as JSON to be stored in the engine. The most common use case for this would be storing the ID of the eCommerce entity next to the resource. It'll be passed with every following request so it's easier for your business logic to create the requests to the eCommerce system without the need of reaching to the database. To persist the custom in the response of the endpoint add the following payload ```json { "resource_customs": { "id": 1, "other_relevent_information": "here" } } ``` The resource custom will only be persisted on 2xx(non-204) HTTP responses. ### Errors handling Handling of the request payload may fail. In such case, there are a couple of scenarios: * failed connection(including 502 and 503 HTTP errors) - the event will be retried a couple of times before aborting completely * 5xx and 3xx HTTP responses * for a single resource, the event is not retried as of an internal error and the history entry is marked with a generic message * for a synchronization error event is going to be retried eventually leading to the failed synchronization status * 4xx HTTP responses * for a single resource * a custom behavior may be applied via an appropriate response ```json { "custom_message": "your custom error message", "retryable": false } ``` retryable parameter determines whether the event can be retried. Otherwise, the fail and custom error message will be applied immediately.\ The message should not exceed the length of 256 chars. If the length is exceeded the message will be truncated. * the event is not retried and the history entry is marked with a generic message * for a synchronization error event is going to be retried eventually leading to the failed synchronization status --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ergonode.com/apps2/detailed-reference/synchronization/synchronization-endpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.