Sign Up
  1. Znode
  2. Solution home
  3. Developer Documentation - V10
  4. API Development - V10

Znode Customization - How to use Znode Events

TABLE OF CONTENTS

Introduction

Znode offers an event-based architecture that allows developers to extend or enhance built-in Znode functions through custom logic, without altering the core product code.


This guide walks through:

  • Component architecture
  • Understanding Znode’s internal event handling
  • Setting up and configuring webhook endpoints
  • Registering events
  • Handling webhook payloads
  • Deploying and testing via Znode CLI


Overview

This guide covers the prerequisites, configuration steps, and implementation details required to handle Znode events via webhooks or message queues. It includes both a high-level summary and technical instructions to help you get started.

This guide will help you:

  • Understand the purpose and application of events in Znode.
  • Configure and host external webhook endpoints using the Custom API SDK.
  • Handle events dynamically in code by switching on event type and name.
  • Deploy and test custom webhook integrations using Znode CLI.
  • Build modular, maintainable custom APIs instead of embedding logic directly in the SDK.
  • Implement real-world use cases such as order processing, dynamic email content, or user onboarding flows.

Component Architecture


  • Znode supports two types of event consumers:
    • Event Consumer (default)
    • Webhook Consumer (if configured in the Znode Admin)
  • By default, Znode uses the Event Consumer mechanism. However, customizations can be implemented using either type of consumer, depending on the project requirements.

Note : This Event Consumer will work only if the custom API application is hosted within the Kubernetes cluster of the Znode BlackBox environment. (The RabbitMQ connection string pointing to the cluster's RabbitMQ pod is configured for the Custom API by the Znode DevOps team.)

  • The Znode API publishes event data to RabbitMQ, which acts as the message broker.
  • The Webhook Consumer functions as a service-based consumer, allowing external services to process and handle customizations based on the published event data.

Note :  Only webhooks configured in Znode Admin for the corresponding event module and event name will be used to transmit event data through the Webhook Consumer.


Prerequisites:

Ensure the following before proceeding:

  • Admin access to the Znode portal.
  • Relevant events are enabled in the Znode database.
  • Znode Admin URL is added to CORS policy in appsettings.json under ZnodeAdminURLCorsPolicy.
  • Custom API SDK is available locally or deployed externally.
  • Familiarity with Znode APIs and general web development practices.

Understanding Znode Events

  • Znode’s core modules (black-box logic) contain predefined event hooks that are triggered during key operations—like order updates, user creation, portal updates, etc.
  • When these events feature is enabled and configured in the database, Znode will invoke a configured webhook URL or RabbitMQ consumer with a detailed JSON payload.
    ✅ Example: If the OrderUpdated event is enabled and mapped, Znode will call your webhook during the relevant order update process..
  • A Google Sheet contains a full list of supported events and their payload schemas. events - Google Sheets.

This sheet serves as a comprehensive reference for developers to understand how to configure and handle various events within Znode.

If you have access to this sheet, you can refer to it for detailed information on each event. 


Webhook request or Event consumer message structure

Below are key fields included in webhook or RabbitMQ-based event consumers:

  • EventDataCode
    • Unique code related to the event. e.g., "MaxwellHardware" for a portal
  • EventDataId
    • Unique ID related to the event. e.g., 2 for user ID
  • EventId
    • Unique system-generated ID for the event.
  • EventModule
    • It Specifies the category or topic of the event, e.g., "Order" to represent the events like "OrderCreated"
  • EventName
    • Descriptive name of the specific event, e.g., "Order" to represent the events like "Created"
  • EventPayload 
    • The object available in the Znode black-box function is passed to your webhook URL via the EventPayload field in the webhook request object.
    • EventPayload is a JSON-stringified representation of the actual objects.
    • The way these are used depends on the choice of the user’s business logic implementation.
  • EventTimeStamp
    • The timestamps indicating when the event data was generated, defaults to the current UTC datetime.
  1. EventType
    • This property is obsolete and will be removed in future releases. Please use the EventModule property instead.
  • EventVersion
    • Version of the event.
  • Source
    • (Optional) The source of the event, useful for identifying where the event originated from.
  • TraceId
    • (Optional) A trace identifier for distributed tracing, used to track events across multiple systems
  • UserId
    • ID of the logged in user who raised the event. Ex. Admin user is logged in and placed the order, then his user id will be set here.(i.e. 2). It may be defaulted or empty for the scheduled events.
  • The webhook URL must be a POST method and it accepts a JSON payload of type eventZnodeActionEvent.

Setting Up Znode Event Consumer

  • Once the Custom API SDK is set up locally, a library called Custom.Libraries.Event is automatically added to the project. This library includes consumers used for creating znode event samples.
  • This library contains example event consumers located at: Custom.Libraries.Event\Consumers\ZnodeEventConsumers
  • Event consumers can further invoke either:
    • Custom APIs via HTTP
    • Znode APIs via SDK or API gateway
  • Consumers are registered in: Custom.Libraries.Event\MessageBroker\MessageBrokerStartup.cs via MessageBrokerStartup.RegisterMessageBroker() method.
  • You can create your own independent consumer logic for advanced scenarios or reuse the sample provided.


Setting Up / Hosting the External URL

  • Once the Custom API SDK is set up locally, a library called Custom.Libraries.Event is automatically added to the project. This library includes controllers and actions used for creating webhook samples.
  • While this library provides a ready-made example, you can also create and deploy an independent custom api webhook using the custom api sdk and znode cli.
  • In an event, you can invoke either custom APIs or Znode APIs using API gateways and clients. The logic varies depending on your specific needs and is not included in the sample.
  • To allow the custom api webhook to be used in the Znode Admin, ensure the admin’s URL is added to the CORS policy in the appsettings.json file located at:

 “\Engine.Custom.Api\appsettings.json > appsettings > ZnodeAdminURLCorsPolicy” key.

This value ensures that the controller accepts cross-origin requests from allowed URLs.
Example : When using the SubscriberEventEvent action in eventEventSubscriberController, ensure the following:

  • The action is a POST method.
  • It accepts a JSON payload of type eventZnodeActionEvent.


the app settings need to be updated as shown below.


  • Handling events in Code : 
    • Within your API, you can handle events using switch on EventType and EventName to apply specific business logic:
  • Once the controller/action/API calls are configured, deployment can be executed using the ZnodeCLI deploy command and subsequently verified in the hosted environment.

Example:
Use the following command to deploy:
Znode deploy CustomAPISDK <Environment> <optional: SDK path>

After deployment, you can access the API via Swagger:

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

This URL can then be configured in the event.



Configuring WebHooks Consumer in Admin:

  • In the Dev Center, a new menu item labeled “Webhook Settings” has been added.
  • Clicking on it opens a page labeled as “Manage Webhook Settings”.
  • This page displays the records created in a grid view with the following columns:
    • Event Module
    • Event Name
    • Webhook URL
    • Is webhook enabled
    • Authorization
    • Action
      • This column has three action icons: “Edit”,  “Delete”, and “Toggle”
        • Clicking on the “Edit” button opens the “Edit Webhook Event” page to edit the configurations against the selected record
        • Clicking on the “Delete” button/Icon deletes the record from the list
        • The toggle icon is used to enable or disable the webhook URL 
  • The webhook URL column in the grid on the “Manage Webhook Settings” page gets truncated after 100 characters. However, hovering over it shows the complete URL.
  •  On the top right side, in parallel with the page title, there is a button labeled “Add New”. 
  • Clicking on it opens a page with the title “Add Webhook Event”.
  • This page has five fields as mentioned below: 
    • Event Module : Lists all modules for which a webhook can be configured (e.g., User, Order, Product).
    • Event Name : Lists available event types: Created, Updated, Deleted.
    • Is Active : Enables or disables webhook event delivery.
    • Webhook Url :     This field is used to specify the Custom API's webhook endpoint. It represents the target API URL that will receive event data via a POST request, with the ZnodeEvent object as the request body. You can provide multiple URLs, separated by commas, to send the same data to different endpoints.
          If you choose to bypass API gateways and access the Custom API directly within the Znode AKS Cluster, you can use the cluster-local root URL http://znode10customapi.znode.svc.cluster.local, followed by your specific Custom API endpoint.
    • Verify Button: The “Verify” button next to the Webhook URL field is used to validate the entered URL. Here's how it works: If the URL is valid and meets all criteria, the following confirmation appears:
      • When the admin enters a URL in the Webhook URL field, the following message appears:“Please verify your URL before proceeding.”
      • The admin must then click the “Verify” button:
        • If the URL is valid and meets all criteria, the following confirmation appears:
          • “The URL is verified successfully.”
        • If the URL is invalid, unreachable, or requires authorization, the following error is shown:
          • “The webhook URL could not be verified because it is either unreachable, not in proper format, or requires an authorization token.”
        • If the URL is valid but requires an access token, the admin should provide it in the “Authorization” field. Once the token is entered, the previous error message disappears, and the system prompts again with:
          • “Please verify your URL before proceeding.”
        • The admin must click “Verify” again. If the access token is valid, the success message reappears:
          • “The URL is verified successfully.”
        • If the token is invalid, the same error message is shown again:
          • “The webhook URL could not be verified because it is either unreachable, not in proper format, or requires an authorization token.”
  • Authorization : API key or token for webhook authentication. It is optional. This can be used when accessing the webhook URL directly—without going through API gateways—or when the Custom API is hosted outside the Znode AKS Cluster and requires a separate authorization header..


      

  •  If a user attempts to create an event with a combination of Event Module and Event Name that already exists, an error will be displayed stating: "WebHookURL is already configured for this event”.
  • To edit an event, the user can modify the "Is Active" status, "Webhook URL", and "Authorization" fields. The "Event Module" and "Event Name" fields are not editable. 

            

     

  • To delete an event, a confirmation prompt appears and only upon confirmation the record is deleted.
  • The “Is Webhook Enabled” field is updated to reflect the enabled or disabled status of the webhook URL only after the user confirms the action through a confirmation prompt.

How to Debug 

  • Webhook
    Prerequisite:

  • The tunnel URL for the Custom API’s local endpoint has been configured using the installed Cloudflared, which is running on the local machine.
    (For more details on Tunneling, refer ERP Setup and Troubleshooting Guide )


Configurations:

  • Configure the Tunnel Webhook URL in the appropriate Event settings and enable the Event. Include the AuthorizationHeader if authentication is required. Also, append the Webhook endpoint route to the Tunnel URL. 


  • If the Webhook URL has the route flash-event-subscriber, the SubscribeZnodeEvent method in the ZnodeEventSubscriberController will be invoked.


  • Consumer 


Prerequisite:

  • RabbitMQ is installed and running on the local machine.
  • CustomAPI SDK setup on the local machine.
  • Configurations:
  • Adding the localhost Connection string of RabbitMQ in appsettings.json located in the path znode10-customapi-sdk\Engine.Custom.Api\appsettings.json.
"EventBus": {

   "MessageBrokerService": "RabbitMQ",

   "ServiceBusConnectionString":  "Endpoint=sb://amlaznode.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=io8cYsJUptzcA0v57SJCm1Udwon83DXul+ASbJ24O+M=",

   "RabbitMQConnectionString": "amqp://guest:guest@localhost:5672",

   "RabbitMQManagementUrl": "http://localhost:15672",

   "RabbitMQUserName": "guest",

   "RabbitMQPassword": "guest",

   "QueueName": "base-cache-queue",

   "RetryCount": "2",

   "RetryInterval": "200",

   "EventRetry": "true"

 }

In the EventBus Section of appsettings.json, set the values of the local RabbitMQ port

  • RabbitMQConnectionString: “amqp://guest:guest@localhost:5672” 
  • RabbitMQManagementUrl: “http://localhost:15672”
  • RabbitMQ typically uses ports 15672 (management UI) and 5672 (AMQP). If your setup uses different port numbers locally, make sure to update them accordingly.
  • These changes are only for debugging purposes, for hosting purposes, use of server configurations.


Debugging Consumer on local machine:

  • The Consume method in ZnodeEventConsumer at path znode10-customapi-sdk\Custom.Libraries.Event\Consumers\ZnodeEventConsumers will receive ZnodeEvent on new User created /updated, Address created /updated, etc.
  • In our hosted environment, events are automatically delivered to the consumer. However, for local debugging purposes, you must manually publish the event using the RabbitMQ Management UI.
  • Steps for publishing ZnodeEvent from the RabbitMQ Management UI for testing purposes
    • Go to RabbitMQ Management UI and log in with UserName: guest, Password: guest
    • Go to Queues and Streams
  • Search Filter: ZnodeEvent-customapi
  • Now select the queue that does not have any suffix  _error or _skipped.
  • Now, scroll down, and open the Publish message section
  • From Z10-22216 | Znode Events   use the appropriate Event Modeldata based on the event you want to trigger.
  • Insert the event payload inside the message property of the following JSON structure:
  • Ensure that the Event Model is enclosed within {} brackets, as the message field expects a valid JSON object.
  "messageType": ["urn:message: Znode.Libraries.Abstract.Event: ZnodeEvent"],

  "message": // Paste your event model data here 

}


  • Publish message
  • You will get hit at ZnodeEventConsumer on the Consume Method


Example 1: Notify Order Creation

Scenario:
 You want to notify user with additional information—like a custom message, promotional code used, or shipping instructions, on top of the order receipt sent to customers.

How to use event:

  • Use the event: Created with Event Module: Order (or similar based on Znode implementation).
  • Create a custom API that notifies user on successful order creation.
  • Register this custom API as a webhook for the event in the Znode database.
  • Your API will be invoked automatically during the order process, allowing dynamic content injection.


Example 2: Notify on User Creation

Scenario:
 You want to notify additional custom details (e.g., referral codes, user tier, or region) at the time of user creation.


How to use event:

  • Use the Event: Created, Event Module: User.
  • Develop a custom API that accepts the user creation payload and writes additional logic to notify the user.
  • Register this API with the event configuration in the database.
  • When a new user is created, Znode triggers the event, and your API enriches the data accordingly.

Out of Scope

This functionality does not include bulk activity-related events(Ex, Bulk import).

    

Queries and Remedies

Find answers to common questions and solutions for common issues when working with custom APIs and events.


  1. Q : How do I deploy the newly created custom API?
    A :
    • Use the command Znode deploy CustomAPISDK <Environment> <optional: SDK path> to deploy changes made in the given folde
    • The changes can be viewed at:
      https://<CustomAPISDKHostedURL>/<Controller>/<Action>
    • You can then use this URL within the Znode admin portal or link it to an event.
  1. Q : How can I display custom table data in a specific section?
    A :
    • Create a custom API that reads data from your custom database table using Znode API conventions.
    • Use this API inside a Znode Custom API webhook or custom admin page.
    • Deploy the custom API using the Znode deploy command.
    • Use the deployed API URL in your event setup.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.

API Development - V10