Webhooks & events

📘
Applicable for AMS & OMS

Introduction

Core-commerce has support for triggering webhooks on events in the Accounts and OMS hubs. These webhooks can be configured through a management endpoint in the API adapter.

::: danger 👉 Multiple callbacksPLEASE NOTE: There is no guarantee that a webhook won't be triggered multiple times from Core-commerce. This means that integration teams are responsible for handling a second callback so no duplicate mails/exports are triggered.

In the header for each webhook the 'messageId' is sent which containers the Servicebus Message identifier. This can be used by integration teams to check if the webhook is already processed.:::

API endpoint

The formatting of both management endpoints is (almost) identical and can be used for CRUD operations.

An endpoint consists of:

EndpointID
Name (internal name, no application)
Endpoint (f.e. https://webhook.site/)
Headers (for possible authentication) (optional)
Events
1. EventType: Service-bus message topic (also see: event types)
2. Path: Addition to the endpoint, example: /test-path/

Webhook message creation

Webhooks are processed based on the messages in the service bus (topic: general). A subscription is registered (xms-schedulewebhooks) for each hub. This subscription is completed by a Container App Job, which is polled every 30 seconds.

This app checks in the webhook configuration whether there are webhooks for the selected event type. If this is the case, it creates a webhook message on a 'webhooks-xms' topic on the service bus (Parameters + naming convention later in explanation).

Webhook processing

Based on the messages in the service bus with the topic 'webhooks-xms', we register a subscription (xms-webhooks) for each microservice. This subscription is completed by a Container App Job, which is polled every 30 seconds, and actually triggers the webhooks. For every processed webhook, the correct Endpoint is retrieved, which means we are always working with current credentials.

Please note: The path is always fixed in the message

The timeout for a called a webhook is set to 30 seconds. After this period the webhook call is failed.

Backoff retry mechanism

Webhooks which return a non-success status code, or run in a time out, are added to the backoff retry mechanism. Other exceptions are not retried, because those are coding issues and should be fixed by the Core-commerce team, for example by adding additional validation. These webhooks are added to the dead-letter-queue after 10 attempts.

Webhooks in the backoff retry mechanism are added to the dead-letter-queue after 15 attempts.

Retry count	Retry in minutes
1	1
2	5
3	15
4	30
5	60
6	120
7	240
= 8	480

Application Insights

There are Application Insights metrics for the webhooks; we need to set these up after going live so we can receive notifications when errors/deadletters occur. To be completed later.

Event types

In the webhooks configuration, the following 'EventType' values can be set for the Accounts and OMS. In the column 'Response parameters' the values which are returned in the webhooks are added.

In the header for each webhook the 'messageId' is sent which containers the Servicebus Message identifier. This can be used by integration teams to check if the webhook is already processed.

Deploy servicebus

For customers who want to use the newsletter, the Servicebus must be deployed.

Accounts event types

Event	Response parameters
account-created	AccountId ConfirmationToken (optional, null when direct activated 'true')
account-confirmed	AccountId
account-reset-password-requested	AccountId ResetPasswordToken TokenValidity (timespan based on .ToString("g"))

OMS event types

Event	Response parameters
channable-order-created	ChannableOrderId
channable-return-request-created	ChannableOrderId ChannableReturnId
channable-return-status-update	ChannableReturnId ReturnState (Options: Accepted, Rejected, Repaired, Keeps, Exchanged, Cancelled)
generate-activation-codes	ActivationCodegroupId ActivationCodeGenerationRequestId AmountOfCodes
order-created	OrderId
order-paid	OrderId
order-payment-added	OrderId OrderPaymentId
order-payment-changed	OrderId OldState NewState OrderPaymentId
order-return-created	OrderReturnId OrderId
order-refund-created	OrderRefundId
order-refund-changed	OrderRefundId
order-state-changed	OrderId

App4Sales addon event types

Event	Response parameters
newsletter-subscribe	Type (Always: Subscribe) EmailAddress IpAddress Language (based on first part of locale) Tags (Added to subscription in Mailchimp for additional information)

Event properties

For each event, a visitor pattern is used to determine which properties can or cannot be send via the webhooks. The following classes contain the mapping schemes, in the tables above the response parameters are shown. New event types also need to be added to this documentation.

Please note: Core-commerce code does not compile if we add a new event type one without implementing the mapping scheme!

::: tip 👉 Service bus performanceWhen you implement the Service Bus in your bespoke application, please make sure that the implementation is compliant with the best-practices from Microsoft. Please see the Best practices for improving Service bus from Microsoft. This means that ServicesBusClient usages should be singletons in your application to keep the connection open.:::

Mapping classes

AmsWebhookDataProvider
OmsWebhookDataProvider