Event Hook: Custom

Adding custom event hooks allows HYPR-enabled sites to gather and interpret HYPR Events using their own custom installation, rather than using HYPR's. By adding an HTTP Event Collector and using its API key to enable HYPR CC's connection, you are able to tailor the output to best suit your needs.

HYPR Events are grouped using the eventTags parameter (AUTHENTICATION, REGISTRATION, ACCESS TOKEN, etc.).

What You'll Need

An administrator account for your SIEM
An administrator account for Control Center
If it is not already enabled, contact HYPR Support to enable Custom Event Hooks for the RP application that you wish to monitor

Setting Up the SIEM

Your SIEM must be configured to communicate with Control Center. Check with your SIEM vendor to obtain the necessary credentials and parameters for the JSON content.

Connecting Custom Event Hooks to HYPR

You will need the Custom Event Hook JSON content to proceed.

Login to HYPR Control Center as an administrator.
In the left navigation menu, click Integrations.
On the Integrations page, click Add New Integration. CC displays available integrations.
Click the tile under Event Hooks for Custom Events.
Click Add New Event Hook.
On the Add New Event Hook dialog, paste the desired JSON content into the text field. See Sample JSON below.
Click Add Event Hook when you are satisfied. CC returns to the Event Hooks page.

Sample JSON using authType BASIC

The below example uses the BASIC authType, which requires basicAuthParameters to be set. This results username/password being included in the Basic Authorization header.

{
  "name":"TestCustomEvents",
  "eventType": "ALL",
  "invocationEndpoint": "https://someurl.com",
  "httpMethod": "POST",
  "authType": "BASIC",
  "authParams": {
    "basicAuthParameters": {
      "username": "grace.hopper@hb.com",
      "password":"M@dH0p$24-7"
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        },
        {
          "key": "Content-Encoding",
          "value": "gzip",
          "isValueSecret": false
        }
      ]
    }
  }
}

Sample JSON using authType API_KEY

The below example uses the API_KEY authType, which requires apiKeyAuthParameters to be set. This results in the bearer token being included in the Bearer Authorization header.

{
  "name":"TestCustomEvents",
  "eventType": "ALL",
  "invocationEndpoint": "https://someurl.com",
  "httpMethod": "POST",
  "authType": "API_KEY",
  "authParams": {
    "apiKeyAuthParameters": {
      "apiKeyName": "Authorization",
      "apiKeyValue": "Bearer XXXXX"
    },
    "invocationHttpParameters": {
      "headerParameters": [
        {
          "key": "Content-Type",
          "value": "application/json",
          "isValueSecret": false
        }
    }
  }
}

JSON schema for authType OAUTH_CLIENT_CREDENTIALS

If your target system uses Oauth for authentication, then set the authType to OAUTH_CLIENT_CREDENTIALS. The authParams element contains invocationHttpParameters as in the above examples, but instead of basicAuthParameters or apiKeyAuthParameters, use oAuthParameters conforming to the below JSON schema.

{
    "oAuthParameters": {
        "clientParameters": {
            "clientId": "string",
            "clientSecret": "string"
        },
        "authorizationEndpoint": "string",
        "httpMethod": "GET"|"POST"|"PUT",
        "oAuthHttpParameters": {
            "headerParameters": [
                {
                    "key": "string",
                    "value": "string",
                    "isValueSecret": true | false
                }
            ],
            "queryStringParameters": [
                {
                    "key": "string",
                    "value": "string",
                    "isValueSecret": true | false
                }
            ],
            "bodyParameters": [
                {
                    "key": "string",
                    "value": "string",
                    "isValueSecret": true | false
                }
            ]
        }
    }
}

Event Hook Entries

Main Entry Parameters

The Event Hooks table displays values for the available Custom Event Hooks. Where applicable, these values are based upon the values used in the JSON content shown above.

Refer the table below for parameters.

Field	JSON Parameter	Description
Name	`name`	The unique name of the Event Hook. This will appear in the RP Applications list in Control Center Standard Mode.
Event Type	`eventType`	The `eventTags` value associated with the Event Hook.admin all authentication deregistration magic_link offline_access registration smart_key web_registration
Endpoint	`invocationEndpoint`	The location of the desired endpoint on the SIEM server.
Auth Type	`authType`	API_KEY \| BASIC \| OAUTH_CLIENT_CREDENTIALS
HTTP Method	`httpMethod`	DELETE \| GET \| HEAD \| OPTIONS \| PATCH \| POST \| PUT
Connection State	N/A	AUTHORIZED \| AUTHORIZING \| CREATING \| DEAUTHORIZED \| DEAUTHORIZING \| DELETING \| UPDATING
Destination State	N/A	ACTIVE \| INACTIVE
Actions (Hover on Options)	N/A	Edit \| Delete See Editing HYPR Custom Event Hooks and Deleting HYPR Custom Event Hooks for how to perform these actions.

Expanded Entry Parameters

Clicking the name of the Event Hook will open a pane with additional information about the entry. As with the above parameters, these reflect the JSON parameter values, where applicable.

Refer the table below for parameters

Field	JSON Parameter	Description
Invocation Endpoint	`invocationEndpoint`	The location of the desired endpoint on the SIEM server. This is the same value shown under the Endpoint column on the Event Hook's main entry.
Auth Params	`authParams`	A data object encompassing `invocationHttpParameters` and one of `basicAuthParameters`, `apiKeyAuthParameters` or `oAuthParameters`.
N/A	`basicAuthParameters`	A data object encompassing user authentication values.
N/A	`username`	The username to authenticate to the SIEM.
N/A	`password`	The password for the username.
N/A	`invocationHttpParameters`	A data object containing HTTP header definitions. See HTTP Headers for a full list of possible headers and acceptable values.
N/A	`headerParameters`	A collection of header parameters for communication with the SIEM. Each header is defined by the following properties: `key`, `value`, and `isValueSecret`.
N/A	`key`	The name of the header parameter being used.
N/A	`value`	The value of the header parameter being used.
N/A	`isValueSecret`	Does this value need to be occluded in the SIEM? true \| false
Connection State Reason	N/A	The reason that the connection is in the connection state.

Clicking Back to Custom Events returns you to the Event Hooks page.

See Event Descriptions: Event Parameters for a full rundown on all Event parameters and their values.

Editing HYPR Custom Event Hooks

On the Custom Events Integration Event Hooks table, on the right side under Actions, click Options-> Edit for the Event Hook you wish to modify.
The Event Hook Details dialog opens. Make changes as needed using the values given in Connecting Custom Event Hooks to HYPR, Step 6, above.
Click Save to return to the Event Hooks page.

Deleting HYPR Custom Event Hooks

In the Event Hooks table, on the right side under Actions, click Options-> Delete for the Event Hook you wish to remove.
The Delete Event Hook dialog opens. Click Delete to remove the event hook.
A dialog appears confirming the Event Hook was deleted. CC returns to the Event Hooks page.

Housekeeping**

You may also wish to delete the related data from your SIEM if it is not used by any other systems.

Sample Event Hook JSON: Device Registration

Initiate Registration

{
 "version": "0",
 "id": "e0932981-65a5-1344-f27e-bcc395837a59",
 "detail-type": "log",
 "source": "hypr_event_hooks",
 "account": "527127228484",
 "time": "2024-07-23T16:01:04Z",
 "region": "us-east-1",
 "resources": [],
 "detail": {
  "data": {
   "id": "409878875789426688",
   "version": 4,
   "type": "AUDIT",
   "eventName": "FIDO2_DEVICE_REG",
   "message": "User example@hypr.com initiated FIDO2 key registration",
   "subName": "/devicemanager/fido2/controlCenterAdmin/attestation/options",
   "eventLoggedBy": "RELYING_PARTY_SERVER",
   "eventTimeInUTC": 1721750462863,
   "loggedTimeInUTC": 1721750462863,
   "tenantId": "mytenant",
   "remoteIP": "76.167.160.255",
   "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
   "traceId": "5ed2c96dbab640b3",
   "additionalDetails": {},
   "deviceType": "WEBAUTHN",
   "rpAppId": "controlCenterAdmin",
   "machineId": "7951a92e1f0860a85d56ec3555a449292438122a7906587d6ebeb4f1791a2e59",
   "sessionId": "gpsx_5GWHjhGEdkxAiUjzj4mWXk",
   "machineUserName": "example@hypr.com",
   "deviceOS": "fido2",
   "serverRelVersion": "9.3.33",
   "origin": "localregion",
   "eventTags": "REGISTRATION",
   "isSuccessful": true
  },
  "dataSource": "cc",
  "date": "20240723",
  "hour": "16",
  "customerUuid": "6c029f8a-6b15-46a4-bfe8-ad69b43c9404",
  "tenantUuid": "baae56f0-52c2-44f2-8ae4-f7d26b49f563",
  "eventTags": [
   "REGISTRATION"
  ]
 }
}

Registration Failure

{
 "version": "0",
 "id": "007a2c58-b2ac-2f31-fdee-bef9b78af97e",
 "detail-type": "log",
 "source": "hypr_event_hooks",
 "account": "527127228484",
 "time": "2024-07-23T16:00:09Z",
 "region": "us-east-1",
 "resources": [],
 "detail": {
  "data": {
   "id": "409878646256140288",
   "version": 4,
   "type": "AUDIT",
   "eventName": "FIDO2_DEVICE_REG_COMPLETE",
   "message": "Challenge is invalid: Session not found for challenge b5jg_tptWGyOmANOQrJKTDVhb2g, possibly expired. Please contact HYPR customer support and report this issue. ExceptionId: 03a393ed-bd36-4867-905c-498de0043993",
   "subName": "/devicemanager/fido2/controlCenterAdmin/attestation/result",
   "eventLoggedBy": "RELYING_PARTY_SERVER",
   "eventTimeInUTC": 1721750408138,
   "loggedTimeInUTC": 1721750408138,
   "tenantId": "mytenant",
   "remoteIP": "76.167.160.255",
   "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
   "traceId": "8dfa004f98988333",
   "additionalDetails": {},
   "errorCode": "1203010",
   "deviceType": "WEBAUTHN",
   "rpAppId": "controlCenterAdmin",
   "sessionId": "b5jg_tptWGyOmANOQrJKTDVhb2g",
   "deviceOS": "fido2",
   "serverRelVersion": "9.3.33",
   "origin": "localregion",
   "eventTags": "REGISTRATION",
   "isSuccessful": false
  },
  "dataSource": "cc",
  "date": "20240723",
  "hour": "16",
  "customerUuid": "6c029f8a-6b15-46a4-bfe8-ad69b43c9404",
  "tenantUuid": "baae56f0-52c2-44f2-8ae4-f7d26b49f563",
  "eventTags": [
   "REGISTRATION"
  ]
 }
}

Registration Success

{
 "version": "0",
 "id": "67aa1a17-bee7-66a4-8f53-1d8977f46a11",
 "detail-type": "log",
 "source": "hypr_event_hooks",
 "account": "527127228484",
 "time": "2024-07-23T16:01:19Z",
 "region": "us-east-1",
 "resources": [],
 "detail": {
  "data": {
   "id": "409878936980127744",
   "version": 4,
   "type": "AUDIT",
   "eventName": "FIDO2_DEVICE_REG_COMPLETE",
   "message": "FIDO2 key (fbfc3007154e4ecc8c0b6e020557d7bd) registered",
   "subName": "/devicemanager/fido2/controlCenterAdmin/attestation/result",
   "eventLoggedBy": "RELYING_PARTY_SERVER",
   "eventTimeInUTC": 1721750476896,
   "loggedTimeInUTC": 1721750477452,
   "tenantId": "mytenant",
   "remoteIP": "76.167.160.255",
   "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
   "traceId": "33935e685859881d",
   "additionalDetails": {
    "extras": {
     "be": "true",
     "bs": "true",
     "rk": "true",
     "transports": "[internal, hybrid]"
    }
   },
   "deviceType": "WEBAUTHN",
   "rpAppId": "controlCenterAdmin",
   "deviceId": "9_dAVI3PhBcVkxugZnUsAg_r2e8",
   "machineId": "d27291371adad3cb5334bee73dcfb98e54b65e2bc2a6045cdd6ecf58f96ee6c6",
   "sessionId": "gpsx_5GWHjhGEdkxAiUjzj4mWXk",
   "machineUserName": "example@hypr.com",
   "authenticator": "fbfc3007154e4ecc8c0b6e020557d7bd",
   "deviceOS": "fido2",
   "serverRelVersion": "9.3.33",
   "origin": "localregion",
   "eventTags": "REGISTRATION",
   "isSuccessful": true
  },
  "dataSource": "cc",
  "date": "20240723",
  "hour": "16",
  "customerUuid": "6c029f8a-6b15-46a4-bfe8-ad69b43c9404",
  "tenantUuid": "baae56f0-52c2-44f2-8ae4-f7d26b49f563",
  "eventTags": [
   "REGISTRATION"
  ]
 }
}

What You'll Need​

Setting Up the SIEM​

Connecting Custom Event Hooks to HYPR​

Sample JSON using authType BASIC​

Sample JSON using authType API_KEY​

JSON schema for authType OAUTH_CLIENT_CREDENTIALS​

Event Hook Entries​

Main Entry Parameters​

Expanded Entry Parameters​

Editing HYPR Custom Event Hooks​

Deleting HYPR Custom Event Hooks​

Sample Event Hook JSON: Device Registration​

Initiate Registration​

Registration Failure​

Registration Success​