How Signal Handlers Work
This article is subject to change as the feature develops and we make improvements.
The calls to perform CRUD operations and to test HYPR Adapt Signal Handlers can be found under Control Center > Adapt > Event (Signal) Handlers in the HYPR Passwordless API collection.
Signal Handlers appear only in Standard Mode: HYPR Adapt.
In Adapt, signals flow through a sequential pipeline of signal handlers. Each handler operates within an isolated ECMAScript runtime environment, without access to browser APIs.
Signal Pipeline
-
Signals enter the system and pass through a series of handlers, one after another.
-
Each handler processes the signal, potentially modifying it (enriching) or performing actions based on the signal's data
-
The signal moves from one handler to the next in the pipeline until it exits, potentially altered or used as a trigger for additional actions
-
Pipelines are unique for each tenant
-
HYPR supplies built in handlers for common use cases. Admin may use them out of the box or further customize them
Built-in Handler
Each pipeline contains an BuiltInSaveEventHandler. This is automatically added to the end of the user defined pipeline. It saves the event after the previous Signal handlers are done processing.
Failed Ingestion
If Adapt fails to ingest an event due to errors in Signal handlers, the event goes into a Dead Letter Queue (DLQ). The failed events may be replayed from the DLQ. This is not exposed to the customers, as of 9.7.
ECMAScript Runtime
-
Each handler uses an ECMAScript runtime, allowing JavaScript-based signal processing
-
The absence of browser APIs means handlers cannot interact with the DOM, manage user interfaces, or utilize client-side features like localStorage or alert
Context API
The system provides a Context API that allows handlers to interact with external systems and perform actions that are not possible within the isolated runtime. This API might include:
-
Logging: Handlers can log information at various levels (e.g., debug, info, warn, error)
-
HTTP Calls: Handlers can make HTTP requests to external services, enabling them to retrieve data or trigger actions outside the system
-
Storage Access: Handlers can store and retrieve data, allowing persistence of state or sharing of data between signals or handlers
-
Configuration Access: Handlers can access settings, enabling dynamic behavior based on external configurations
Handler Behavior
-
Signal Enrichment: Handlers can modify the signal object by adding additional data, such as metadata, computed values, or information retrieved from external sources; the enriched signal is then passed down the pipeline
Example: A handler might add context data based on inbound IP address
-
Triggering Actions: Handlers might use the signal as a trigger to perform side actions, such as sending notifications or invoking external systems; these actions can be performed without altering the signal itself
Example: A handler might trigger a change in shipment process
Sequential Processing
-
Handlers are arranged in a defined order within the pipeline. Each handler processes the signal sequentially, ensuring that each handler's modifications or side effects occur in a specific order
-
After processing, the final signal state is either output from the pipeline or stored, depending on the system's design
Summary
This system supports complex signal-driven workflows where signals can be enriched or used as triggers for other actions. By leveraging a Context API for external interactions, the handlers maintain a focused role in signal processing, ensuring security, modularity, and efficient signal handling.