Skip to main content

Inbound Webhooks

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.

In some use cases, third parties need to invoke Adapt via web hooks for pushing data in. For example, this is the flow for Microsoft:

Control Center (CC) API​

CC exposes a dedicated API for inbound webhook calls. The API signature is flexible to accomodate multiple HTTP methods and content types.

[GET | POST | PATCH | DELETE] /cc/api/integrations/adapt/webhookclient/{source}/{name}

Path Variables​

  • source: Source of the Event hook call; for example: Microsoft
  • name: Identifier for the call, to distinguish between multiple calls from the same source

Request Body​

There are no restrictions on the Request Body. These content type(s) are accepted:

  • application/json
  • text/html
  • application/xml
  • multipart/form-data

Request Handling​

CC converts the inbound API call into an INBOUND_WEB_HOOK Event (below), then sends it to the Adapt ingest API. Adapt sends it down the pipe, where a Signal Handler is expected to respond.

"message" to mapOf(
      "id" to UUID.randomUUID().toString(),
      "eventName" to "INBOUND_WEB_HOOK",
      "eventTimeInUTC" to Date().time.toString(),
      "loggedTimeInUTC" to Date().time.toString(),
      "webhook" to mapOf(
          "source" to source,
          "name" to name
      ),
      "tenantUuid" to adaptClient.tenantUuid(),
      "eventTags" to "ADAPT",
      "httpRequest" to mapOf(
          "method" to httpReq.method,
          "uri" to httpReq.requestURI,
          "body" to httpReq.reader.readText(),
          "headers" to inputHeadersMap,
          "queryString" to httpReq.queryString,
          "remoteIP" to httpReq.remoteIPAddress
      ),
  )

Calling the Event Hook​

POST Example

curl -X POST --location "http://localhost:8009/cc/api/integrations/adapt/webhookclient/microsoft/register" \
    -H "Authorization: Bearer <API token for CC admin app with applications scope>" \
    -H "Content-Type: application/json" \
    -d "{ \"Abc\":  100 }"

GET Example

curl -X GET --location "http://localhost:8009/cc/api/integrations/adapt/webhookclient/microsoft/register?foo=aaa" \
    -H "Authorization: <API token for CC admin app with applications scope>" \
    -H "Content-Type: text/html"

Event Handler​

Handle the INBOUND_WEB_HOOK Event and return an httpResponse attribute in the response. This is parsed by CC and passed back as the HTTP response.

Response​

The handler must return an object response. The handler may add any data attributes it obtained from the inbound Event to the result object. This result object will be processed by the rest of the handler pipeline and eventually saved.

Note that Adapt will automatically enhance the JS result with the following attributes:

  • id
  • tenantUuid
  • tenantId
  • eventTimeInUTC

Returning a Response to the Webhook Call​

The response from the Signal Handler must include an httpResponse attribute of the following form:

{
    "statusCode": 202,
    "body": { "attr": "value}" },
    "headers": { "Content-Type": "application/json" }
  }

This will be returned as a response to the webhook call.

Testing the Webhook​

Testing can be performed in Control Center.