Signal Handlers Structure

Beta Feature

This article is subject to change as the feature develops and we make improvements.

API Calls

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.

Standard Mode Only

Signal Handlers appear only in Standard Mode: HYPR Adapt.

Signal Handlers collect or add additional information to signal data, or perform triggered actions upon specified events. At its core, each Event handler follows this flow:

• Intake the signals as a JSON object

• Perform enrichment or actions

• Return the processed Event

function handle(event) {
  // Every event being processed by Adapt is passed to each signal handler in the pipeline
  let input = JSON.parse(event);

  // Retrieve the configuration from the 'configuration' tab in the UI
  let config = JSON.parse(ctx.getConfig());
  let eventName = input?.eventName;

  // Check if this is one of the events we want to enrich
  if (config.eventsToEnrich.includes(eventName)) {

    // Add custom action here to add more info to your event
    // Good practices:
    // - Keep event size small, helps performance aspects
    // - Avoid making calls to third party APIs, helps performance aspects
    // - Do not change original signal attributes. Add enriched data in a separate attribute

    input.enrichedData = {myAttribute: true}
  }

  // This returned event will go down the pipeline and will be saved to Adapt
  return JSON.stringify(input);
}

ctx.log("FINE", "Custom signal enricher done");
handle(ctx.getEventAsJson());

Capturing Execution Statistics

Data Collectors

In data collectors, we need to capture two kinds of data:

• Pull

  • Save the actual data to be collected

  • Update the TRIGGER event signal indicating that data was collected. The signal handler Id is used as the entityId on the trigger event.

• Inbound event hook

  • Save the actual data to be collected

  • Update the INBOUND_WEB_HOOK event signal indicating that data was collected. The signal handler Id is used as the entityId on this event.

Action Handlers

Perform the desired action.

Update the inbound action event, indicating that an action was performed. Typically include some stats around the action. The signal handler Id is used as the entityId on this event.

Example:

Updating an inbound event (TRIGGER / INBOUND_WEB_HOOK / ACTION), to track that it was handled:

  // `event` is the event being handled
  // Save this action event by the handler which processed it
  event.entityIdOrName = ctx.getEventHandlerId();
  event.isSuccessful = true;
  event.source = "HYPR";
  event.msg = msg;

Event Enrichers

These handlers enrich (update) the event they are handling, typically by adding more attributes, and then returning it.

They do not save anything directly. Saving is done at the end by BuiltInSaveEventHandler.

Restrictions on Event Enrichers

Event enricher signal handlers are not allowed to directly modify the event they're handling. This is because we do not want to lose track of the original event received. This is for:

• Auditing purposes

• To be able to replay the original event in the future; for example, if changes are made to a signal handler and now we want to re-ingest the data through the new signal handler

What Can They Do Instead?

Event enrichers may add new data to an event by adding a new attribute called enrichedData to the original event.

This attribute must be a JavaScript object or a map. Example:

// `event` is the event being handled
event.enrichedData = { isTorExitNode: true, myPersonalTag: "TOR" } 

Special Event Attributes

Some Event attributes have special meaning to the Adapt system.

Attribute	Description
skipSaveEvent	If this is set to true, the Event will not be persisted.
id	Treated as the unique id for an event. Adapt adds id automatically with a UUID if it is missing.
eventTimeInUTC	Time at which the event took place in the real world. Adapt adds this attribute automatically with the current time if it is missing.
eventTags	Free text tags indicating the broad category of the event. This can be multiple tags separated by spaces.

See Event Descriptions for a full list of Event attributes.

Error Handling

Adapt signal handler framework captures any JS Error thrown from the code. These are recorded by the signal handlerId and shown on the CC UI, under the signal handler.

Example:

throw Error(`Failed to send msg to Slack`);

Security Model

• Custom handlers carry some risk since they run user code. User uploaded code could be malicious. This risk is mitigated by:

  • Running in a Lambda function, leverage the Lambda sandboxing

  • Use Polyglot sandboxing provided by GraalVM; JS code cannot escape into the host process

• A handler only has access to its own secrets and no other handler's secrets

• Domains to which HTTP calls are allowed can be allowlisted in tenant configuration; HYPR has full visibility on these calls since the Lambda makes them on behalf of the user code

• Everything happens in the context of the tenantUuid, preventing lateral movement across tenants