Technical Support | Suprema

1. Overview

This document describes the mechanism by which a device delivers log events to external systems using Webhooks, ensuring reliable event delivery across unstable network conditions.

The design goals of this mechanism are:

• Prevent log loss during network outages

• Automatically retransmit logs accumulated while offline

• Seamlessly transition back to real-time event delivery

• Support configurable retry policies

• Allow configurable handling of logs after retry exhaustion

2. Core Concepts

The device operates in two transmission modes depending on network availability and webhook delivery results:

All logs are managed using a last successfully sent log identifier, ensuring ordered delivery and avoiding duplication.

3. System Components

3.1 Webhook Endpoints

3.2 Log Metadata

3.3 Retry Policy Configuration

Webhook retry behavior is governed by configuration parameters.

4. Retry Mechanism

4.1 General Retry Flow

1. Webhook delivery attempt fails

2. Retry count is incremented

3. If retryCount < maxRetryCount

   • The device waits for the configured retry interval

   • A retry attempt is performed

4. If retryCount ≥ maxRetryCount

   • Retry attempts are terminated

   • Log handling proceeds based on the configured policy

4.2 Log Handling After Retry Exhaustion

Once the maximum retry count is reached, log handling behavior depends on configuration.

4.2.1 Discard Mode

discardOnRetryFail = true

• Behavior:

  • The log is marked as permanently failed

  • The log is removed from local storage

  • Processing continues with subsequent logs

• Characteristics:

  • Prevents indefinite retries and resource exhaustion

  • Log loss is possible

• Emitted Event:

  • DEV_WEBHOOK_SEND_FAIL

4.2.2 Retain Mode

discardOnRetryFail = false

• Behavior:

  • The log is retained in local storage

  • The device remains in or transitions to Offline Mode

  • The log is included in subsequent retransmission loops

• Characteristics:

  • Guarantees log preservation

  • Ensures retransmission once connectivity is restored

  • May increase local storage usage

5. Offline Log Delivery (Retry Applied)

5.1 Offline Webhook URL Available

• Logs are collected in batches (up to 10 entries)

• Batches are sent to the Offline Webhook URL

• Retry count is tracked per individual log

Result Handling

• Emitted Events:

  • DEV_WEBHOOK_SEND_BULK_SUCCESS

  • DEV_WEBHOOK_SEND_BULK_FAIL

5.2 Offline Webhook URL Not Available

• Logs are processed individually

• Logs are sent to the Online Webhook URL

• The same retry policy is applied

6. Real-Time Event Processing (Retry Applied)

Once the device is considered online, new events are processed in real time.

Processing Steps

1. Event occurs

2. A single log entry is collected

3. The log is sent to the Online Webhook URL

4. Retry is performed upon failure

6.1 Result Handling

7. State Transition Summary (Including Retry)

[Online]
   └─ Delivery failure
        └─ Retry attempts
             ├─ Success → [Online]
             └─ Retry exhausted
                   ├─ Discard → [Online]
                   └─ Retain  → [Offline]

8. Design Characteristics and Benefits

• Configuration-driven retry and log retention policies

• Protection against infinite retry loops

• Guaranteed delivery for critical logs when retention is enabled

• Resilient operation in unstable network environments

• Efficient batching for offline log retransmission

9. Conclusion

This webhook delivery architecture provides a robust and flexible mechanism for device-originated event transmission.

By combining retry control, configurable log retention, and automatic online/offline state management, the system ensures high reliability while allowing operators to balance resource usage and delivery guarantees according to operational requirements.