Edit in GitHubLog an issue

Event-based integrations

The following sections demonstrate all the event-based integrations that Adobe Commerce integration starter kit has to offer, including webhook ingestion, event handler actions and event ingestion actions.

Ingestion webhook

The Adobe Commerce integration starter kit supports ingestion webhooks. They provide an alternative method to deliver events for scenarios where the calling system cannot produce a request to interact directly with the event provider. For example, if the client cannot add custom headers to the request.

Enabling ingest webhooks

To enable webhooks in the starter kit, uncomment the ingestion section in your app.config.yaml file:

Copied to your clipboard
ingestion:
license: Apache-2.0
actions:
$include: ./actions/ingestion/actions.config.yaml

Customizing ingest webhooks

Data parameters contain the information of the event to publish. Each event must include an entity, event, and value. The value parameter contains the data to send through the event.

The following entities and their corresponding events are currently available:

  • product
    • be-observer.catalog_product_create
    • be-observer.catalog_product_update
    • be-observer.catalog_product_delete
  • customer
    • be-observer.customer_create
    • be-observer.customer_update
    • be-observer.customer_delete
  • customer-group
    • be-observer.customer_group_create
    • be-observer.customer_group_update
    • be-observer.customer_group_delete
  • order
    • be-observer.sales_order_status_update
    • be-observer.sales_order_shipment_create
    • be-observer.sales_order_shipment_update
  • stock
    • be-observer.catalog_stock_update

The following JSON payload demonstrates a product entity with a create event:

Copied to your clipboard
{
"data": {
"uid": "event_uid_1",
"event": "be-observer.catalog_product_create",
"value": {
"sku": "PRODUCT_SKU",
"name": "Product SKU",
"price": 1,
"description": "Product SKU description"
}
}
}

Authentication and parameters

Ingest webhooks are not authenticated by default. To add authentication and enable an authentication check, modify the actions/ingestion/webhook/auth.js file's checkAuthentication function.

You can access any needed environment parameter from params. Use the following parameters to inform your .env authentication settings.

You can provide additional .env parameters by adding them to the inputs section of the actions/ingestion/webhook/actions.config.yaml file:

Copied to your clipboard
webhook:
function: ./consumer/index.js
web: 'no'
runtime: nodejs:16
inputs:
LOG_LEVEL: debug
OAUTH_ORG_ID: $OAUTH_ORG_ID
OAUTH_CLIENT_ID: $OAUTH_CLIENT_ID
OAUTH_CLIENT_SECRET: $OAUTH_CLIENT_SECRET
OAUTH_TECHNICAL_ACCOUNT_ID: $OAUTH_TECHNICAL_ACCOUNT_ID
OAUTH_TECHNICAL_ACCOUNT_EMAIL: $OAUTH_TECHNICAL_ACCOUNT_EMAIL
IO_MANAGEMENT_BASE_URL: $IO_MANAGEMENT_BASE_URL
IO_CONSUMER_ID: $IO_CONSUMER_ID
IO_PROJECT_ID: $IO_PROJECT_ID
IO_WORKSPACE_ID: $IO_WORKSPACE_ID
AIO_runtime_namespace: $AIO_runtime_namespace
YOUR_PARAM: $YOUR_PARAM_ENV
annotations:
require-adobe-auth: false
final: true

consumer action

The main purpose of this action is to route events to the event handler action. Normally, this routing is determined by the name of the event received.

The consumer action is subscribed to a set of events. In many cases, all the events originate from the same entity, such as the product entity. However, there are examples where a consumer receives events from multiple entities belonging to the same "domain", such as order and shipment. When the event provider receives an event, this runtime action will be automatically activated.

The response returned by a consumer action is expected to be consistent with the response received from the activation of the subsequent event handler action. For example, if the event handler action returns an HTTP/400 status, the consumer action is expected to respond with the same status. This ensures that the event processing is appropriately retried based on the event handler action response.

When it receives an event that it does not know how to route, it is expected to return HTTP/400 status. This will prevent the event handling from being retried.

By default, consumer actions have the following response:

Copied to your clipboard
// ./actions/responses.js#successResponse
return {
statusCode: 200,
body: {
type: 'EVENT TYPE',
response: {
// Response returned by the event handler action
}
}
}

event handler action

The main purpose of this action is to manage an event that notifies you about a change in one of the integrated systems. Typically, its business logic includes an API call to propagate the changes to the other system being integrated.

The consumer action synchronously activates these event handler actions to delegate the handling of an event.

The response returned by an event handler action includes a statusCode attribute. This attribute allows the consumer action to propagate the response HTTP status code upstream to properly reflect the event registration information located on the Debug Tracing tab in the Adobe Developer Console.

By default, event handler actions have the following response:

Copied to your clipboard
// ./actions/responses.js#actionSuccessResponse
return {
statusCode: 200,
body: {
success: true,
message: 'YOUR SUCCESS MESSAGE'
}
}

event ingestion action

The main purpose of this runtime action is to provide an alternative method to deliver events to the integration, if the 3rd-party, backoffice application cannot fulfill the Events Publishing API's requirements.

For more information, see Ingestion webhooks.

To get the URL of the webhook, run the following command:

Copied to your clipboard
aio runtime action get ingestion/webhook --url

By default, event ingestion actions have the following response:

Copied to your clipboard
// ./actions/responses.js#successResponse
return {
statusCode: 200,
body: {
type: 'EVENT TYPE',
response: {
success: true,
message: 'Event published successfully'
}
}
}

Sample code

The Adobe Commerce Extensibility Code Samples repository contains samples that illustrate the following concepts:

Next steps

  • Privacy
  • Terms of Use
  • Do not sell or share my personal information
  • AdChoices
Copyright © 2024 Adobe. All rights reserved.