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 POST.

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. HTTP POST request is sent to the configured endpoint.
5. External endpoint processes data.
6. 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.
Method	Currently supports POST method.
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

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.

Webhook Payload Structure

All webhook payloads are JSON formatted.

Common Attributes

Example: Reward Awarded

{
    "event_id": "8ab4bda7-7296-4b5e-b0d9-6039773c2dc3",
    "event_type": "reward.awarded",
    "event_timestamp": "2023-10-05T14:20:00Z",
    "schema_version": "1.0.0",
    "data": {
        "awarded_reward": {
            "transaction_id": "2555babf-2ca8-4e72-a275-81a4d06152e5"
            "reward_id": "REW-12343",
            "member_id": "john.new@example.com",
            "note": str or null,
            "awarded_by": "Journey",
            "journey_id": "6ab8391a-250c-473b-a1bc-828a3de66390"
            "awarded_at": "2023-10-05T11:15:00Z",
        }
    }
}

Example: Badge Awarded

{
    "event_id": "8ab4bda7-7296-4b5e-b0d9-6039773c2dc3",
    "event_type": "badge.awarded",
    "event_timestamp": "2023-10-05T11:15:00Z",
    "schema_version": "1.0.0",
    "data": {
        "awarded_badge": {
            "id": "2c73c62a-98b7-4448-a6e5-aecc6567ddb5",
            "awarded_at": "2023-10-05T11:15:00Z",
            "awarded_by": "Journey",
            "journey_id: "d7e63a79-571a-41a1-b470-bf164ed70714",
            "expiry_date": "2023-10-05T11:15:00Z or null",
            "is_expired": false
            "note": "Awarded for Journey Test",
            "badge_id": "3895bbdf-5d6a-40de-a45e-9e1cef10949e",
            "member_id": "john.new@example.com",
        }
    }
}

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.