The 1st method - Webhook Message Consumer

Overview

• This is the first way of communication:
  • To register consumer and consume events of application domain services using message gateway
  • Webhook API is following the REST API guidelines
  • The event messages are supported by .NET connectors of platform services using nuget packages

Message Gateway

MessageGateway is platform service encapsulating external communication with message broker to HTTP based technologies, gRPC and Webhooks. It is the only way for external cloud and on-premise services integrated with AVAplace platform.

See more: OIDC/OAuth2 authentication

How webhooks work (short overview)

A webhook is a lightweight HTTP callback used to deliver events in near real-time. You register a consumer webhook URL in the MessageGateway and, when an event occurs, the gateway sends an HTTP POST to that URL with a JSON payload and security headers.

Key expectations for consumers:

• Verify the JWT in the Authorization header (RS256) and validate X-MessageSecurityCode.
• Process payloads idempotently and use messageId/path variables for deduplication and correlation.
• Return an HTTP 2xx response to acknowledge the message; non-2xx responses or network errors trigger redelivery with retry/backoff.
• Prefer separate webhook URLs per stage (DEMO/PROD) and per message type when practical.

How to consume webhook message using message gateway

• Register MessageGateway consumer using REST API
• Register consumer(s) for event(s) to consume filtered message queue(s) via Webhook URL
• Use HTTP client to obtain payload when a message is delivered

Webhook URL template

• Consumer webhook URL is provided by developer partner, e.g. https://yourwebhookapi.com/webhook
• It is recommended to use different URL for each stage (DEMO and PROD)

POST {webhookUrl}/{messageType}/{contractType}/{messageId}

path variable	description
messageType	name of the message type (routing key)
contractType	name of the class/contract
messageId	unique id of the message

Webhook request headers

Sample of request headers (shortened):

Authorization: Bearer ...
Content-Type: application/json; charset=utf-8
X-MessageSecurityCode: Dx_...
X-Tenant-Id: ...
X-UserClaim-Actort: ...
X-UserClaim-client_id: ...
X-UserClaim-iss: ...
X-UserClaim-locale: ...
X-UserClaim-orgs_codes: ...
X-UserClaim-sub: ...
X-UserClaim-tid: ...
X-UserClaimsExtended: ...

header	description
Authorization	JWT token
X-MessageSecurityCode	The message security code for the message.
X-Tenant-Id	Tenant identification .
X-UserClaim-Actort	Person id (Actor) in JWT standard.
X-UserClaim-client_id	Client identification.
X-UserClaim-iss	Issuer
X-UserClaim-locale	Language and region code with RFC 5646, ISO-639-2.
X-UserClaim-orgs_codes	Selected organizations (organization.code) - Organization national number|Country code.
X-UserClaim-sub	UserId (SSO unique identifier).
X-UserClaim-tid	Name for selected TenantId.
X-UserClaimsExtended	Extended claims

Sample of UserClaimsExtended request header (shortened):

[
  { "Key": "nbf", "Value": "..." },
  { "Key": "idp", "Value": "..." },
  { "Key": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "Value": "..." },
  { "Key": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "Value": "..." },
  { "Key": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname", "Value": "..." },
  { "Key": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname", "Value": "..." },
  { "Key": "tname", "Value": "..." },
  { "Key": "organizations", "Value": "..." }, 
  { "Key": "auth_orgs", "Value": "..." },
  { "Key": "auth_orgs_codes", "Value": "..." },
  { "Key": "jti", "Value": "..." },
  { "Key": "iat", "Value": "..." }
]

Webhook request body

Message is sent in HTTP body in JSON format.

Authorization

Each request to webhook consumer contains JWT token in Authorization header. JWT token is signed with RS256 algorithm. You can verify signature using modulus and exponent that you can get from configuration of identity provider.

OpenID configuration

https://[hostname]/api/asol/idp/.well-known/openid-configuration

Message acknowledgment and redelivery

Examples - OrderReleased scenario

Webhook URL

POST https://yourwebhookapi.com/webhook/ASOL.PlatformStore.OrderReleased/OrderReleased/c0eb0000-5dfe-0015-8604-08dbd6ef8bf7

path variable	value
messageType	ASOL.PlatformStore.OrderReleased
contractType	OrderReleased
messageId	unique for each receive message

Webhook headers

Authorization: Bearer ...
Content-Type: application/json; charset=utf-8
X-MessageSecurityCode: Dx_...
X-Tenant-Id: ASOLEU-DEV-fd9ad6b9-2f29-4c7a-9a3a-c7469e19b1ff
X-UserClaim-Actort: c042e6ad-f293-4e36-8266-574b665792ff
X-UserClaim-client_id: plaza-pass
X-UserClaim-iss: https://demo.avaplace.com/api/asol/idp
X-UserClaim-locale: cs-CZ
X-UserClaim-orgs_codes: 64949541|CZ
X-UserClaim-sub: 6388701d4a20a1c1bc1f0831
X-UserClaim-tid: ASOLEU-DEV-fd9ad6b9-2f29-4c7a-9a3a-c7469e19b1ff
X-UserClaimsExtended: [{"Key":"nbf","Value":"1698409522"},{"Key":"idp","Value":"local"},{"Key":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name","Value":"petr.tomala@assecosol.com"},{"Key":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress","Value":"petr.tomala@assecosol.com"},{"Key":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname","Value":"Petr"},{"Key":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname","Value":"Tomala"},{"Key":"tname","Value":"ASOLEU-DEV"},{"Key":"organizations","Value":"fff2d400-9838-4513-9c7b-535a03bd8c94"},{"Key":"auth_orgs","Value":"fff2d400-9838-4513-9c7b-535a03bd8c94"},{"Key":"auth_orgs_codes","Value":"64949541|CZ"},{"Key":"jti","Value":"9781FBFE8F78C7F7802F494947860804"},{"Key":"iat","Value":"1698409522"}]

Webhook body

{
  "orderId": "b0588700-f3a2-4bde-bbb4-d2022bf7851e",
  "productId": "98fa6110-ec8b-45a4-882f-b5a1e89812ca",
  "vendorCode": "64949541|CZ"
}

See examples:

• Consume OrderReleased notification using webhook