HTTP Webhook Plugin

Relevant source files

• src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs
• src/ThingsGateway.Plugin.Mqtt/MqttCollect/MqttCollect.cs
• src/ThingsGateway.Plugin.OpcUa/Pages/OpcUaMasterRuntimeRazor.razor.cs

The HTTP Webhook Plugin is a data publishing plugin that forwards collected industrial data, device status, alarms, and system events from the ThingsGateway platform to external HTTP endpoints via POST requests. It transforms runtime data into JSON payloads and delivers them to configurable webhook URLs, enabling integration with REST APIs, cloud platforms, and custom web services.

This document covers the webhook publisher implementation. For other data publishing mechanisms, see MQTT Client Plugin, Kafka Producer Plugin, and RabbitMQ Producer Plugin. For data collection, see Data Collection Plugins.

Plugin Architecture

The Webhook class extends BusinessBaseWithCacheIntervalScriptAll, inheriting caching, interval-based processing, and C# scripting capabilities from the base plugin infrastructure.

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs1-266

Data Flow and Event Processing

The webhook plugin processes four types of runtime events, each triggering a distinct data pipeline from event detection to HTTP POST delivery.

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs27-261

Variable Data Processing

Variable data follows the most complex processing path, with support for grouping and batching strategies.

Change-Based Processing (lines 102-165):

• VariableChange() is called when a variable's value changes
• If GroupUpdate is enabled and BusinessGroupUpdateTrigger is true, the entire BusinessGroup is queued as a batch
• Otherwise, the single variable is queued

Time-Interval Processing (lines 97-150):

• VariableTimeInterval() is called periodically based on configured intervals
• Variables are separated into grouped and ungrouped collections
• Grouped variables are queued by their BusinessGroup identifier
• Ungrouped variables are either batched (if EnableAtomicBatchEnqueue is true) or queued individually

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs97-165

Device Status Processing

Device status updates follow a simpler path without grouping logic.

Change-Based: DeviceChange() queues individual DeviceBasicData objects when device status changes (lines 69-75)

Time-Interval: DeviceTimeInterval() queues a batch of device status records at scheduled intervals (lines 62-68)

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs62-86

Alarm Processing

Alarm events are queued immediately upon detection:

• AlarmChange() checks if AlarmTopic is configured
• Creates a CacheDBItem<AlarmVariable> wrapper
• Queues to _memoryAlarmModelQueue for batch processing

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs27-41

Plugin Event Processing

System events (device connections, plugin state changes) follow the same pattern as alarms:

• PluginChange() checks if PluginEventDataTopic is configured
• Queues PluginEventData objects for delivery

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs44-58

Queue Processing and Update Methods

Each data type has corresponding update methods that process queued items in batches.

Update Method	Queue Source	Topic Generation Method	Data Type
UpdateVarModel()	_memoryVarModelQueue	GetVariableBasicDataTopicArray()	VariableBasicData
UpdateVarModels()	_memoryVarModelQueue	GetVariableBasicDataTopicArray()	List<VariableBasicData>
UpdateDevModel()	_memoryDevModelQueue	GetDeviceTopicArray()	DeviceBasicData
UpdateDevModels()	_memoryDevModelQueue	GetDeviceTopicArray()	List<DeviceBasicData>
UpdateAlarmModel()	_memoryAlarmModelQueue	GetAlarmTopicArrays()	AlarmVariable
UpdatePluginEventDataModel()	_memoryPluginDataModelQueue	GetPluginEventDataTopicArrays()	PluginEventData

All update methods follow the same pattern:

1. Extract items from the queue (already wrapped in CacheDBItem<T>)
2. Call the corresponding topic generation method (inherited from base class)
3. Pass the resulting TopicArray[] to Update() for HTTP delivery
4. Return OperResult indicating success or failure

Variable Filtering: UpdateVarModel() applies an optional online filter using LINQ: WhereIf(_driverPropertys.OnlineFilter, a => a.IsOnline == true) (line 255)

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs79-257

HTTP Request Execution

TopicArray Structure

The TopicArray class (inherited from base infrastructure) contains:

• Topic: The webhook URL endpoint
• Payload: Serialized JSON byte array

Topic generation methods (provided by base class) transform runtime data objects into TopicArray instances based on configured topic templates and C# script transformations.

WebhookUpAsync Method

The core HTTP POST logic is implemented in WebhookUpAsync():

Key Implementation Details:

• Uses ByteArrayContent for efficient payload handling (line 177)
• Sets Content-Type: application/json header (line 178)
• Returns detailed error messages including HTTP status codes (line 204)
• Logs queue count (_memoryVarModelQueue.Count) for monitoring (lines 191, 193)
• Supports two logging modes: detail (full payload) and count-only (lines 188-199)

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs169-212

Update Method (Batch Iterator)

The Update() method iterates through multiple TopicArray items, sending each to its configured endpoint:

Behavior:

• Short-circuits on cancellation (line 226-227)
• Tracks success state to avoid duplicate logging (line 228)
• Returns immediately on first failure (lines 236-239)
• Only logs on state transitions (success → failure or vice versa)

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs216-243

Configuration Properties

The Webhook class uses a WebhookProperty configuration object (not shown in provided files, but referenced via _driverPropertys). Based on usage patterns:

Property	Type	Description	Used In
AlarmTopic	string	Webhook URL for alarm events	Line 29
PluginEventDataTopic	string	Webhook URL for plugin events	Line 46
DeviceTopic	string	Webhook URL for device status	Lines 64, 71
VariableTopic	string	Webhook URL for variable data	Lines 110, 154
GroupUpdate	bool	Enable variable grouping by BusinessGroup	Line 112
EnableAtomicBatchEnqueue	bool	Batch enqueue ungrouped variables	Lines 122, 137
OnlineFilter	bool	Only send variables with IsOnline == true	Line 255
DetailLog	bool	Enable full payload logging (trace level)	Line 188

Topic Configuration: Each data type can be routed to a different webhook URL by configuring the corresponding topic property. Empty or whitespace topics disable that data type.

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs29-255

Variable Grouping and Batching

The plugin supports two complementary mechanisms for aggregating variable data before transmission.

Business Group Aggregation

Variables can be assigned a BusinessGroup identifier (a string property on VariableBasicData). When GroupUpdate is enabled:

Change-Based Grouping (lines 156-159):

• Individual variable changes can trigger group-level updates
• Checks BusinessGroupUpdateTrigger flag on the variable
• Looks up all variables in the same group via VariableRuntimeGroups dictionary
• Converts the entire group to VariableBasicData using AdaptListVariableBasicData()
• Queues the group as a single batch

Interval-Based Grouping (lines 115-133):

• During interval processing, variables are grouped using LINQ GroupBy(a => a.BusinessGroup)
• Variables with empty BusinessGroup are processed separately
• Each group is queued as a distinct batch

Purpose: Groups variables that logically belong together (e.g., all tags from a single device) into a single HTTP POST, reducing request overhead.

Atomic Batch Enqueueing

When EnableAtomicBatchEnqueue is true (lines 122-124, 137-139):

• All ungrouped variables from an interval are queued as a single List<VariableBasicData>
• Triggers UpdateVarModels() instead of multiple UpdateVarModel() calls
• Results in a single TopicArray with all variables serialized together

When false:

• Each variable is queued individually
• Each triggers a separate UpdateVarModel() call
• May result in multiple HTTP requests

Trade-off: Batching reduces HTTP overhead but increases payload size and delays delivery until the full batch is ready.

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs108-165

Error Handling and Logging

Success State Tracking

The plugin maintains a volatile bool success field (line 324 in similar pattern) to track connection state:

• Compares current result with previous state (line 228)
• Only logs when state changes to avoid log spam
• Logs warnings when transitioning to failure state (line 232)

HTTP Error Responses

Non-successful HTTP responses are converted to OperResult errors:

• Captures the StatusCode (line 204)
• Returns descriptive message: "Failed to trigger webhook. Status code: {StatusCode}"
• Caller can inspect OperResult.IsSuccess and OperResult.ErrorMessage

Exception Handling

All exceptions during HTTP POST are caught and wrapped (lines 207-210):

• Creates OperResult(ex) with exception details
• Preserves stack trace for debugging
• Prevents plugin crash from network errors

Logging Levels

The plugin supports granular logging based on LogLevel:

Level	Condition	Output	Location
Trace	DetailLog == true && LogLevel <= Trace	Full payload details + queue count	Line 191
Debug	DetailLog == true && LogLevel <= Debug OR DetailLog == false && LogLevel <= Debug	Count summary only	Lines 193, 198
Warning	State change to failure	Error message with details	Line 232

Methods Used:

• GetDetailLogString(topicArray, queueCount): Full serialization
• GetCountLogString(topicArray, queueCount): Summary statistics

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs169-243

Integration with ThingsGateway Runtime

Data Type Mapping

The plugin works with four ThingsGateway runtime data types:

Runtime to Transfer Conversion:

• VariableRuntime → VariableBasicData: Snapshot containing current value, timestamp, quality
• DeviceRuntime → DeviceBasicData: Status, online state, error messages
• Alarms and plugin events are not converted (passed directly)

CacheDBItem Wrapper: All queue items are wrapped in CacheDBItem<T>, which adds:

• Enqueue timestamp
• Retry count
• Expiration metadata

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs27-165

Plugin Lifecycle

The Webhook class participates in the standard plugin lifecycle:

1. Configuration Loading: Properties loaded from _driverPropertys
2. Initialization: Base class sets up queues and interval timers
3. Event Registration: Runtime callbacks registered for variable/device/alarm changes
4. Processing Loop: Background tasks dequeue items and call update methods
5. Disposal: HTTP client disposed, queues cleared

The plugin extends BusinessBaseWithCacheIntervalScriptAll, which provides:

• AddQueue*() methods for thread-safe enqueueing
• Update*() abstract methods for batch processing
• Interval-based timer management
• C# scripting support for topic/payload transformation
• Automatic queue management with expiration

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs24-265

Class Member Summary

Key Fields

Field	Type	Purpose
client	HttpClient	Reusable HTTP client for POST requests (line 167)
success	volatile bool	Tracks last operation result for state change logging
_driverPropertys	WebhookProperty	Configuration properties (not shown, inherited)
_businessPropertyWithCacheIntervalScript	Object	Base class config with topic URLs (lines 29, 46, 64, 110)

Override Methods

Method	Base Class	Purpose
AlarmChange()	BusinessBaseWithCacheIntervalScriptAll	Queue alarm on change (line 27)
PluginChange()	BusinessBaseWithCacheIntervalScriptAll	Queue plugin event on change (line 44)
DeviceChange()	BusinessBaseWithCacheIntervalScriptAll	Queue device on change (line 69)
DeviceTimeInterval()	BusinessBaseWithCacheIntervalScriptAll	Queue devices on interval (line 62)
VariableChange()	BusinessBaseWithCacheIntervalScriptAll	Queue variable on change (line 102)
VariableTimeInterval()	BusinessBaseWithCacheIntervalScriptAll	Queue variables on interval (line 97)
UpdateVarModel()	BusinessBaseWithCacheIntervalScriptAll	Process single variable queue (line 87)
UpdateVarModels()	BusinessBaseWithCacheIntervalScriptAll	Process variable list queue (line 92)
UpdateDevModel()	BusinessBaseWithCacheIntervalScriptAll	Process single device queue (line 79)
UpdateDevModels()	BusinessBaseWithCacheIntervalScriptAll	Process device list queue (line 83)
UpdateAlarmModel()	BusinessBaseWithCacheIntervalScriptAll	Process alarm queue (line 33)
UpdatePluginEventDataModel()	BusinessBaseWithCacheIntervalScriptAll	Process plugin event queue (line 50)

Private Helper Methods

Method	Signature	Purpose
TimeIntervalUpdateVariable()	(List<VariableBasicData>)	Apply grouping/batching logic (line 108)
UpdateVariable()	(VariableBasicData)	Handle single variable change (line 152)
Update()	(IEnumerable<TopicArray>, CancellationToken)	Iterate and POST all topics (line 216)
WebhookUpAsync()	(TopicArray, CancellationToken)	Execute single HTTP POST (line 169)

Sources: src/ThingsGateway.Plugin.Http/Webhook/Webhook.other.cs1-266