TABLE OF CONTENTS

• Introduction
• Component Architecture
  • Event Consumer Notes
  • Webhook Consumer Notes
• Prerequisites
• Understanding Znode Events
• Webhook Request or Event Consumer Message Structure
• Setting Up Znode Event Consumer
• Hosting the External Webhook URL
• Enabling the Event Feature in the Database
• Configuring Webhook Consumer in Admin
  • Manage Webhook Settings Page
• How to Debug
  • Webhook Debugging
  • Consumer Debugging
• Examples
• Example 1: Notify on Order Creation
  • Example 2: Notify on User Creation
• Out of Scope
• Queries and Remedies
  • Q: How do I deploy a custom API?
  • Q: How can I display custom table data?

Introduction

This document provides an overview of the event mechanism used in Znode for supporting customizations. It includes the design architecture, setup, implementation details, and sample use cases. The intended audience includes Znode custom implementation developers—both internal and external.

Znode features an event-based architecture that allows developers to extend or enhance built-in functionality through external logic—without altering the core Znode codebase.

This covers:

• Component architecture
• Znode's internal event handling
• Webhook and RabbitMQ endpoint setup
• Event registration and payload structure
• Deployment and testing using Znode CLI

This article helps developers:

• Understand the purpose and application of Znode events
• Configure and host external webhook endpoints using the Custom API SDK
• Handle events dynamically using custom logic
• Deploy and test event handlers using Znode CLI
• Build modular, maintainable extensions using APIs instead of SDK modifications
  
  

Supported use cases include dynamic order processing, email generation, and user onboarding flows.

Component Architecture

Znode supports two event consumer types:

• Event Consumer (Default) – Internal RabbitMQ-based consumer
• Webhook Consumer – Configured in Znode Admin for external webhook handling
  
  

Event Consumer Notes

• Functional only when hosted inside Znode’s Kubernetes cluster
• RabbitMQ is pre-configured by the Znode DevOps team
• Publishes messages to RabbitMQ, which acts as the event broker
  
  

Webhook Consumer Notes

• Used when webhook URLs are defined in Znode Admin
• Triggers external API endpoints with a JSON payload
• Event data is only sent to the configured webhooks for specific modules and names
  
  

Prerequisites

Ensure the following:

• Admin access to the Znode Admin Console
• Relevant events are enabled in the database
• Znode Admin URL is added to the ZnodeAdminURLCorsPolicy key in appsettings.json
• Custom API SDK is installed or accessible
• Familiarity with Znode APIs and general web development
  
  

Understanding Znode Events

Znode core modules contain predefined hooks triggered by system activities (e.g., order creation, user registration).

When enabled in the database and configured correctly, Znode triggers these events via either:

• RabbitMQ queue
• Webhook POST requests
  
  

Example: The OrderCreated event sends the payload to your webhook or message consumer during the order process.

Webhook Request or Event Consumer Message Structure

Each event payload contains:

• EventDataCode: Unique business identifier (e.g., Store Code)
• EventDataId: Primary ID of the record (e.g., User ID)
• EventId: System-generated unique event identifier
• EventModule: Domain area of the event (e.g., Order, User)
• EventName: Action type (e.g., Created, Updated)
• EventPayload: JSON-stringified object with event details
• EventTimeStamp: UTC of event occurrence
• TraceId (optional): For distributed tracing
• UserId: ID of the user who triggered the event
• Source, EventVersion, and EventType (deprecated)
  
  

Webhook URLs must support POST requests and accept JSON payloads of type eventZnodeActionEvent.

Setting Up Znode Event Consumer

Once the Custom API SDK is set up, a library named Custom.Libraries.Event is added, which includes:

• Sample consumers at: Custom.Libraries.Event\Consumers\ZnodeEventConsumers
• Message broker registration logic: MessageBrokerStartup.RegisterMessageBroker()

Consumers can invoke:

• Custom APIs
• Znode APIs using SDK or API gateways
  
  

Developers can extend or replace sample consumers with custom logic.

Hosting the External Webhook URL

To set up a webhook controller:

• Ensure ZnodeAdminURLCorsPolicy is correctly configured in \Engine.Custom.Api\appsettings.json
• Define a POST endpoint to accept the eventZnodeActionEvent payload
  Example: A controller action named SubscribeZnodeEvent in ZnodeEventSubscriberController

After configuration:

• Deploy using Znode CLI
  
  

Znode deploy CustomAPISDK <Environment> <optional: SDK path>

• Verify in Swagger:

https://<customapi-url>/swagger/index.html

Enabling the Event Feature in the Database

To activate events, insert or update the following setting in the ZnodeGlobalSetting table:

Insert:

INSERT INTO dbo.ZnodeGlobalSetting (FeatureName, FeatureValues, FeatureSubValues, CreatedBy, CreatedDate, ModifiedBy, ModifiedDate)
SELECT 'ZnodeFeatureFlashEvents', '', 'true', 2, GETDATE(), 2, GETDATE()
WHERE NOT EXISTS (
    SELECT TOP 1 1 FROM ZnodeGlobalSetting WHERE FeatureName = 'ZnodeFeatureFlashEvents'
)

Update:
This step will become unnecessary once the feature is enabled by default in future releases.

UPDATE ZnodeGlobalSetting
SET FeatureSubValues = 'true'
WHERE FeatureName = 'ZnodeFeatureFlashEvents'

Configuring Webhook Consumer in Admin

Navigate to Dev Center > Webhook Settings to manage event webhooks.

Manage Webhook Settings Page

To add a new event:

• Click “Add New”
• Fill in required fields
• Save the configuration
  
  

How to Debug

Webhook Debugging

Prerequisites:

• Tunnel setup using Cloudflared
• Local Custom API webhook route is configured and publicly accessible
  
  

Steps:

• Map tunnel to local endpoint
• Add the tunnel URL (with webhook route) in Znode Admin webhook settings
• Enable the event
• On event trigger, the controller method will be invoked
  
  

Consumer Debugging

Prerequisites:

• RabbitMQ installed and running locally
• Custom API SDK configured
• Update the appsettings.json:
  
  

"EventBus": {
  "MessageBrokerService": "RabbitMQ",
  "RabbitMQConnectionString": "amqp://guest:guest@localhost:5672",
  "RabbitMQManagementUrl": "http://localhost:15672",
  "RabbitMQUserName": "guest",
  "RabbitMQPassword": "guest",
  "QueueName": "base-cache-queue",
  "RetryCount": "2",
  "RetryInterval": "200",
  "EventRetry": "true"
}

Publishing Events for Testing:

• Log in to RabbitMQ Management UI
• Navigate to Queues → Select ZnodeEvent-customapi
• Go to “Publish Message”
• Use the following JSON format:
  
  

{
  "messageType": ["urn:message:Znode.Libraries.Abstract.Event:ZnodeEvent"],
  "message": {
    // Event model content
  }
}

• Submit to trigger the consumer
  
  

Examples

Example 1: Notify on Order Creation

Goal: Send custom notifications (e.g., promotional codes, shipping instructions)

• Event Module: Order
• Event Name: Created
• Create a webhook or consumer to receive the payload and send a notification
  
  

Example 2: Notify on User Creation

Goal: Enrich user onboarding with region, tier, or referral data

• Event Module: User
• Event Name: Created
• Create a webhook to process and log/enhance data
  
  

Out of Scope

Bulk event triggers (e.g., CSV imports) are not currently supported by this mechanism.

Queries and Remedies

Q: How do I deploy a custom API?

A:
 Use the following CLI command:

Znode deploy CustomAPISDK <Environment> <optional: SDK path>

Access your endpoint via:

https://<CustomAPISDKHostedURL>/<Controller>/<Action>

A:

• Create a custom API to read from your table
• Deploy using Znode CLI
• Use the URL in webhook or the custom Admin Console section