Skip to main content

Signal Handler Context API

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.

The signal handler is pure ECMAScript and is restricted to run in the Lambda sandbox. The context object provides controlled access to external environment.

Context object is available to the handler code via the ctx variable.

Methods​

  • log(level, msg)

    • Log to the Lambda execution logs

      • level: INFO | FINE | FINER | WARNING | SEVERE

      • msg: String msg to log

    • Keep INFO logging minimal to help with stored logs volume. Example:

      ctx.log("INFO", "Handling inbound web hook request");

  • getEventAsJson()

    • Get the Event being handled; example:

      let event = ctx.getEventAsJson();
      JSON.parse(event);

  • getConfig()

    • Get the configuration (from the Configuration UI) as JSON string

    • Configuration is expected to contain parametrized values; for example the URL of an external service to connect to, shown in the following configuration:

      Can be accessed as:

      let confStr = ctx.getConfig();
      let conf = JSON.parse(confStr);
      ctx.log("INFO", "url=" + conf["url"]);

  • httpGet(String url, Map<String, String> headers)

    • Make an HTTP GET call to an external service

      url http url

    • Headers to pass on to the GET request. Content-Type and Accept headers are added by default with a value of application/json

    • Response

      • Map with following attributes:

        • statusCode of the response from the GET request

        • Headers on the response from the GET request

        • Body of the response from the GET request

        let getResp = ctx.httpGet(
          "https://check.torproject.org/exit-addresses", 
          {"Cache-Control" : "no-cache"});
        let body = JSON.parse(getResp).body;

  • httpPost(String url, String body, Map<String, String> headers)

    • POST version of the httpGet method (above)

    • body parameter is passed unaltered on the POST request

  • readEvent(String entityIdOrName, long startDate, long endDate)

    • Look up stored Event data for the tenant

    • startDate - endDate: The range to search for the saved Event; dates are expressed in milliseconds since epoch

  • saveEvent(String eventSource, String eventName, String entityIdOrName, Map<String, Object> event)

Limitations on Signal Handlers​

Version 9.0+

Signal Handler code is not allowed to modify the following security-sensitive attributes on the Event object, if they are present on the inbound Event. This allows a handler to add these if they are missing, but prevents it from making modifications.

  • id

  • tenantUuid

  • deviceId

  • machineUserName

  • entityIdOrName

  • eventTime

  • source

  • eventName

If these are modified, they will be reset, and a warning will be logged.

{
  "level": "WARNING",
  "message": "Modifying attribute=\"entityIdOrName\" is not allowed. original=\"3e800e02-6d8f-4aa1-928e-6d0831ebeb24\", new=\"changed\", reverted",
  ...
  "attribute": "entityIdOrName",
  "new": "changed",
  "original": "3e800e02-6d8f-4aa1-928e-6d0831ebeb24"
}