Summary

The Webhook enables real-time event delivery from the Annex Cloud Loyalty Platform to external customer systems.

Whenever a configured event occurs (such as User Creation, User Update, Reward Issued, Tier Upgrade, etc.), the system automatically triggers a webhook and sends event data to the configured external endpoint via HTTP method.

This eliminates dependency on batch jobs or manual synchronization processes and ensures real-time integration across systems.

Webhooks provide:

• Real-time event synchronization
• Reduced system latency
• Lower network traffic
• Improved operational efficiency
• Seamless integration with CRM, CDP, ESP, OMS, and other external platforms

Push vs Pull Model

Webhook Model:
Events are automatically pushed when triggered.

API Model:
External systems must continuously poll for updates.

Navigation
Annex Cloud > Webhook

Webhook Module Capabilities

The Webhook module allows administrators to:

• Create webhook
• Configure event subscriptions
• Define filters
• Configure authentication
• Enable/Disable endpoints
• Monitor delivery logs
• Test webhook endpoints

Configuration is available via:

• User Interface
• REST APIs

Webhook Architecture

Real-Time Integration Flow

1. Event occurs in Annex Cloud (e.g., User Update).
2. The system detects the event.
3. Payload is prepared.
4. External endpoint processes data.
5. Delivery status is logged.

No batch processing. No delay.

Webhook Page Components

1. Webhooks Tab: Displays all configured webhook endpoints including name, URL, status, success rate, enable/disable toggle, and actions.
2. Audit Logs Tab: Displays the log history of webhook events, including details such as Event ID, delivery status (Success or Failed), status code, error messages (if any), and timestamps. This information helps track webhook event processing and troubleshoot delivery issues.
3. Select Start Date: Filters webhook records from a specific start date.
4. Select End Date: Filters webhook records up to a specific end date.
5. Name Field: Search webhooks using the webhook name.
6. Search Button: Applies selected filters (Start Date, End Date, Name) and refreshes the grid.
7. + Create Webhooks: Opens the webhook configuration wizard to create and configure a new webhook endpoint.

Webhook List View

The Webhook List View displays all configured webhooks in the system.

Fields and Functionality

 

 

Field	Explanation
Name	Displays the webhook name entered during configuration.
URL	Displays the endpoint where event data is delivered.
Status	Displays whether the webhook is Active or Inactive. If the most recent trigger fails, the status is displayed as Failed.
Success Rate	Displays the percentage of successful deliveries compared to total triggers. Success Rate Calculation Success Rate = (Successful Deliveries ÷ Total Trigger Attempts) × 100 It represents the percentage of successfully delivered webhook events. Example: 9 successful out of 10 attempts → 90% 3 successful out of 3 attempts → 100%
Last Success	Displays the date and time of the last successful event delivery.
Last Failure	Displays the date and time of the last failed attempt.
Create Date	Displays when the webhook was created in the system.
Enable Toggle	Allows administrators to enable or disable the webhook. Use the Enable toggle to: Activate the webhook Temporarily disable it without deleting configuration
Actions	Displays management options for the webhook.     Delete – Permanently removes the webhook after confirmation.   View Logs – Opens the Audit Logs page filtered for the selected webhook to review delivery status and errors.

 

Creating a Webhook

Click Create Webhooks to begin configuration.

The setup is divided into three steps:

1. Endpoint Details
2. Event Subscriptions
3. Securities & Retries

Step 1: Endpoint Details

Field Explanations

Security & Authentication

Select the authentication method used to secure webhook requests.

1. JWT: Uses secret token validation to verify webhook requests.

2. Basic Auth: Requires the following credentials to authenticate the webhook request:

a. User Name: Enter the user name for Basic Authentication.

b. Password: Enter the password for Basic Authentication.

3. Signature: Uses a shared secret key to generate a request signature. The receiving system must validate the signature included in the webhook request to ensure the payload is authentic and has not been tampered with.

The Secret Token ensures that only authenticated and trusted requests are accepted by the external system.

After successful verification, the system displays a Verified confirmation.

Step 2: Event Subscriptions

In this step, administrators select:

• Feed Type
• Event Types to trigger

Administrators can select which events should trigger the webhook.

Supported Feed Types

1. User
2. Badge
3. Reward
4. Journey
5. Point Balance
6. Fraud Detection
7. Tier
8. Transaction

Event Type Explanation

1. If Feed Type = User

      Available Events:

• Create
• Update

Example Scenario – User Create

When a new user is created:

• Webhook is triggered
• Member data (First Name, Last Name, Opt-in Status, etc.) is sent to the endpoint
• Customer system receives the data in real-time

Example Scenario – User Update

If a user updates their last name:

• System detects the update
• A new webhook event is triggered
• Updated data is sent immediately
• Downstream system updates its records

This ensures real-time data consistency.

2. If Feed Type = Badge

Available Event:

• Award

Example Scenario – Badge Award

When a badge is awarded to a member:

• The webhook is triggered.
• Badge details (Badge Name, Badge ID, Member Info, Date Awarded, etc.) are sent to the configured endpoint.
• The external system receives the update in real-time.

3. If Feed Type = Reward

Available Events:

• Award
• Expiry
• Low Coupon Alert

Example Scenarios

Reward Award

• When a reward is issued to a member, the webhook sends reward details instantly.

Reward Expiry

• When a reward expires, the webhook notifies the external system.

Low Coupon Alert

• When reward inventory falls below a defined threshold, a webhook alert is triggered.

This helps external systems monitor reward lifecycle and inventory.

4. If Feed Type = Journey

Available Events:

• In Progress
• Completed
• Abandoned

Example Scenarios

Journey In Progress

• Triggered when a member starts a journey.

Journey Completed

• Triggered when a member successfully completes the journey.

Journey Abandoned

• Triggered when a member exits or does not complete the journey.

This enables real-time journey tracking and automation.

5. If Feed Type = Point Balance

Available Events:

• User
• Group

Example Scenarios

User

• Triggered when an individual member’s point balance changes.
• Updated balance details are sent instantly.

Group

• Triggered when group-level point balance changes occur.
• Updated group balance details are shared with the endpoint.

6. If Feed Type = Fraud Detection

Available Events:

• Alert.General
• Alert.BarrierFree
• Alert.Transfer

Example Scenarios

Alert.General

Triggered when the system identifies suspicious member activity based on configured fraud detection rules.

Example:
A member performs multiple loyalty activities within a short period, such as repeated purchases, point earning transactions, redemptions, or account-related actions that match configured fraud detection criteria. The fraud detection engine identifies the activity as suspicious and triggers an Alert.General webhook event.

Fraud alert details, member information, and activity information are sent to the configured endpoint for review and further investigation.

Alert.BarrierFree

Triggered when a redemption transaction with a configured action attribute is detected within the specified time duration, generating a Barrier-Free fraud alert.

Example:
A member exceeds a configured transaction threshold or performs activities that fall outside expected behavioral patterns. The system identifies the activity as a potential fraud risk and generates an Alert.BarrierFree webhook event.

The alert details and related member information are immediately delivered to the configured endpoint so external systems can review and investigate the activity.

Alert.Transfer

Triggered when suspicious point transfer activity is detected between members or accounts.

Example:
A member transfers a large number of loyalty points to another account within a short period of time. Based on configured fraud detection rules, the system identifies the transfer as potentially fraudulent and triggers an Alert. Transfer webhook event.

Transfer details, member information, and fraud alert information are sent immediately to the configured endpoint for monitoring and investigation.

7. If Feed Type = Tier

Available Events:

• Change

Triggered whenever a member's tier status changes.

Tier changes can occur due to:

• Initial tier assignment when a member joins the program
• Tier upgrade
• Tier downgrade
• Tier re-qualification or renewal

The webhook provides information about the member's current tier, previous tier, next tier (if applicable), action type, tier identifiers, tier names, and tier effective dates.

Example – Tier Upgrade

A member earns enough qualifying points/spend/subscription to move from the Silver tier to the Gold tier. The system identifies the tier upgrade and triggers a Change webhook event.

The payload contains the current tier (Gold), previous tier (Silver), next available tier (Platinum), action type, and related tier information. The updated tier details are sent to the configured endpoint.

Example – Tier Downgrade

A member no longer meets the qualification requirements needed to maintain their current tier. The system processes the downgrade and triggers a Change webhook event.

The webhook payload includes the member's current tier, previous tier, next tier information, and action type indicating a downgrade. The updated tier details are delivered to the configured endpoint.

Example – Tier Re-qualification

A member successfully satisfies the requirements needed to retain their existing tier during the maintenance period. The system identifies the re-qualification and triggers a Change webhook event.

The payload includes the member's current tier information and an action type indicating re-qualification. This ensures external systems remain synchronized with the member's tier status.

Example – Initial Tier Assignment

When a member joins the loyalty program, they are assigned to the program's starting tier. The system triggers a Change webhook event and sends the member's current tier information, tier identifiers, tier name, and effective date to the configured endpoint.

This allows external systems to track the member's tier journey from the moment they enroll in the program.

8. If Feed Type = Transaction

Available Events:

• User
• Group

Event Type Explanation

User

Triggers whenever a loyalty transaction or activity occurs for an individual member.

A transaction is not limited to points activity. Any loyalty-related activity performed by a member can generate a transaction event.

Examples include:

• Purchase transactions
• Non-purchase activities
• Account creation or enrollment
• Subscription activities
• Points credits
• Points debits
• Redemptions
• Manual adjustments
• Custom loyalty actions
• Any configured loyalty transaction activity

The webhook sends transaction details related to the selected transaction type and configured action.

Group

Triggers whenever a transaction affects a group-level account.

Examples include:

• Group points credits
• Group points debits
• Hierarchy-level adjustments
• Group purchase activities
• Group redemption activities
• Group transaction corrections
• Custom group actions

The webhook sends group transaction details to the configured endpoint.

Transaction Type

Administrators can further filter transaction events by transaction type:

• Credit
• Debit
• Both

Example Scenarios

User Credit Transaction

When a credit transaction is successfully processed for a member, the webhook is triggered immediately and transaction information is sent to the configured endpoint.

Example

A customer receives 100 points through a Manual Credit/Debit action.

Result

• Transaction Type = Credit
• Event = User
• Webhook is triggered
• Transaction information is delivered to the external system

User Debit Transaction

When a debit transaction is processed for a member, the system generates a webhook event and sends the updated transaction information to the configured endpoint.

Example

A customer redeems points and 50 points are deducted from their account.

Result

• Transaction Type = Debit
• Event = User
• Webhook is triggered
• Updated transaction details are sent

User Activity Transaction

Triggered whenever a member performs a loyalty activity that generates a transaction.

Example

A customer joins the loyalty program, completes a purchase, performs a non-purchase activity, subscribes to a loyalty offering, or completes a custom loyalty action.

The activity generates a transaction record and the system triggers a User transaction webhook event. Transaction details, member information, and activity information are sent to the configured endpoint.

Group Credit Transaction

When points are credited at the group level, the group balance is updated and a webhook event is generated.

Example

An administrator credits 500 points to a family or hierarchy group.

Result

• Transaction Type = Credit
• Event = Group
• Webhook is triggered
• Group transaction details are delivered

Group Debit Transaction

When points are deducted from a group account, the transaction is processed and a webhook event is generated.

Example

A group redeems points or an administrator performs a manual debit adjustment against the group account.

Result

• Transaction Type = Debit
• Event = Group
• Webhook is triggered
• Updated transaction details are sent

Group Activity Transaction

Triggered whenever a transaction impacts a group-level account.

Example

A hierarchy group receives points through a group-level earning activity, purchase activity, redemption activity, or manual adjustment.

The system processes the transaction and triggers a Group transaction webhook event. Group details, transaction information, and updated balances are delivered to the configured endpoint.

Transaction Actions

Administrators can select one or more loyalty actions that should trigger the webhook.

Administrators can select one or more loyalty actions that should trigger the webhook.

Examples include:

• Manual Credit/Debit
• Hierarchy Group Manual Credit/Debit
• Manual Spend Adjustment
• Custom Actions
• Any configured loyalty action available in the tenant

Only transactions generated through the selected actions will trigger the webhook.

Action-Based Transaction Webhooks

Webhook delivery can be restricted to specific actions.

Example – Manual Credit/Debit

If the administrator selects:

• Event = User
• Transaction Type = Credit
• Action = Manual Credit/Debit

The webhook will trigger only when a Manual Credit transaction occurs for a member.

Example – Hierarchy Group Manual Credit/Debit

If the administrator selects:

• Event = Group
• Transaction Type = Debit
• Action = Hierarchy Group Manual Credit/Debit

The webhook will trigger only when a debit transaction is performed at the group level through the selected action.

Example – Manual Spend Adjustment

If the administrator selects:

• Event = User
• Transaction Type = Both
• Action = Manual Spend Adjustment

The webhook will trigger whenever a Manual Spend Adjustment creates either a Credit or Debit transaction.

After selecting the required event subscriptions, click Next to continue to the next configuration step.

For detailed information about the webhook payload structure, refer to Webhook Payload Structure

Step 3: Securities & Retries

This section controls retry behavior and security configurations.

Administrators can configure:

1. Retry attempts
2. Retry Delay
3. Request Timeout

In this step, administrators configure delivery reliability and request handling settings for the webhook.

This ensures secure, stable, and controlled webhook execution.

1. Retry Attempts

Defines the number of times the system will retry sending the webhook if delivery fails.

1. If the endpoint does not respond
2. If a timeout occurs
3. If a non-success HTTP status is returned

Example:
If Retry Attempts = 3
The system will try delivering the webhook up to 3 additional times after the initial failure.

This helps prevent data loss due to temporary network or server issues.

2. Retry Delay

Defines the time interval between each retry attempt.

• Configured in seconds
• Applied between consecutive retry attempts

Example:
If Retry Delay = 30 seconds
The system waits 30 seconds before attempting the next retry.

This prevents overwhelming the receiving system.

3. Request Timeout

Defines the maximum time the system waits for a response from the endpoint.

• Configured in seconds
• If no response is received within this time, the request is marked as failed
• Retry logic (if configured) will then be triggered

Example:
If Request Timeout = 15 seconds
If the endpoint does not respond within 15 seconds, the attempt fails and a retry begins.

Click Save to create the webhook.

After saving, the webhook appears in the Webhooks tab.

Audit Logs

The Audit Logs tab provides detailed tracking of webhook delivery attempts, responses, and errors. It helps administrators monitor performance and troubleshoot failures.

Audit Log Filters

1. Start Date – Displays logs created on or after the selected date.
2. End Date – Displays logs created on or before the selected date.
3. Select Webhook – Displays logs related to the selected webhook only.
4. Search – Applies selected filters and refreshes the results.

Audit Log Columns

• Webhook Name – Displays the name of the triggered webhook.
• Event ID – Displays the unique identifier for the webhook event.
• Status – Displays the final delivery result (Success/Failure).
• Status Code – Displays the HTTP response code returned by the endpoint.
• Error – Displays error details if the delivery failed.
• Delivered At – Displays the date and time of successful delivery.
• Created At – Displays the date and time when the event was generated.