UniFi Identity Enterprise - Event Hooks

Event Hooks is a notification system that allows Identity Enterprise to send workspace events to third-party services. It operates by making HTTP requests to your endpoint URL and delivering events in JSON format within the request body. 

To set up an event hook, you need to implement a web service with an internet-accessible endpoint.

Create an Event Hook

1. Go to your Identity Enterprise Manager > Lab > Integration > Event Hook.
2. Click + New Event Hook.
3. Complete the required fields:
   • Name: Enter a name for the event hook.
   • Apply to: Choose whether this event hook applies to the entire workspace or specific sites.
   • Endpoint URL: Provide the URL where Identity Enterprise will send the events.
   • (Optional) Authentication field: For enhanced security and to secure the communication channel between Identity Enterprise and your third-party service, enter the name of the authorization header.
   • (Optional) Authentication secret: For enhanced security and to secure the communication channel between Identity Enterprise and your third-party service, enter the value that corresponds to the field name.
   • (Optional) Click Add Field to include additional HTTP headers that offer extra context or metadata about the event.
4. Scroll down to the Event Subscriptions section and select the checkboxes for the events you want to subscribe to.

5. Click Create.

Verify Your Ownership of Endpoint URL

After creating an event hook, Identity Enterprise needs to verify your ownership of the endpoint URL. By clicking Verify, Identity Enterprise will make a one-time GET verification request to your endpoint, passing your service a verification value that your service needs to send back. 

1. Identity Enterprise sends GET requests to your endpoint with an HTTP header named x-uid-challenge. 
2. Your service must read this header value and return it in the response body within a JSON object named verification. For example: { "verification": "the value from header" }.

Event Hook Delivery

When an event matching the type monitored by your event hook occurs, the event hook is triggered automatically. It sends a request to your external service with a JSON payload containing event details. Event delivery is made on a best-effort basis, ensuring that events are delivered at least once, though delays may occur due to network conditions.

{
"version": "0.0.1",
"data": {
"uuid": "604ff411-5aae-4b07-8a6e-257bbc4a40d6",
"event": {
"company_id": "d6337d83-b4bf-4e10-a1e6-bb6bf883c8d5",
"display_message": "Logined",
"level": "normal",
"published": 1631693430560,
"reason": "",
"result": "SUCCESS",
"type": {
"category": "USER",
"site": "7654cd3e-dec4-4b65-ad06-fab15e52d040",
"unique_key": "user.session.start"
}
},
"target": [
{
"display_name": "Identity Enterprise Manager Portal",
"platform": "Mac OS",
"type": "web"
}
]
}
}