Custom Event Push Systems of Record enable real-time event streaming from external systems that do not support the Shared Signals Framework (SSF). This integration allows you to push arbitrary JSON events to SGNL, where they are stored in the graph and can be used to trigger CAEP Hub Actions and dynamic access control policies.
Unlike traditional Systems of Record that periodically synchronize data or SSF-based event streams that follow standardized protocols, Custom Event Push accepts arbitrary JSON payloads from any system capable of making HTTP POST requests. This makes it ideal for integrating with proprietary systems, legacy applications, SIEM platforms, and other tools that generate security or business events but don’t support modern event streaming standards.
Custom Event Push is particularly valuable for organizations that need to incorporate events from diverse systems into their access control decisions. When security events, business process changes, or system state modifications occur in source systems, they can be pushed to SGNL to update graph state and trigger downstream actions, enabling comprehensive, real-time access orchestration workflows.
Important Event Retention Characteristics: Event Push events are retained in the SGNL graph for a maximum of 30 days. Additionally, each subject (as identified by the configured subject identifier) can have a maximum of 50 event types associated with it.
Event Push Systems of Record operate differently from traditional polling-based integrations. Instead of SGNL periodically requesting data from external systems, external systems actively push events to SGNL when they occur.
Event Push accepts arbitrary JSON payloads, making it compatible with a wide range of systems. The integration supports:
Single Event Payloads: Individual events sent as single JSON objects Batched Event Payloads: Multiple events sent in a single request as JSON arrays Mixed Event Types: Different types of events can be included in the same payload
While Event Push accepts arbitrary JSON, each event must meet certain requirements to be processed successfully:
Unique Event ID: Each event must include a unique identifier (not limited to JTI format) Subject Identification: Each event must include at least one subject identifier Authentication or Signing: Events must be authenticated using bearer tokens or cryptographically signed (one or both methods) Event Type Identification: Events must include information to identify their type for proper processing
Event Push is designed to work with various types of systems:
Identity Providers: Okta Event Hooks, Azure Event Subscriptions for Entra ID, and other identity system events Security Tools: SIEM platforms, endpoint detection systems, and security monitoring tools Business Applications: JIRA webhooks, ServiceNow events, and custom application events Infrastructure Systems: Monitoring tools, log aggregation systems, and operational platforms
Custom Event Push Systems of Record support Bearer Token Authentication:
SGNL generates authentication tokens that event sources must include in the Authorization header when delivering events. This method provides authentication for event sources and is managed through SGNL’s token generation system.
Event Push Systems of Record use custom SoR templates that define the event structure and processing configuration. Use the following template as a starting point for Okta Event Hooks:
displayName: "OKTA event hooks"
description: "OKTA event hooks Event Stream"
type: EventStreams-1.0.0
deliveryMethod: eventPush
pushType: Custom
pushEventsPath: $.data.events[*]
entities:
UserLifecycleDeactivate:
displayName: User Lifecycle Deactivate
externalId: user.lifecycle.deactivate
pushExternalId: $.eventType
description: User Lifecycle Deactivate
pageSize: 1000
pagesOrderedById: false
attributes:
- name: id
externalId: $.uuid
type: String
indexed: true
uniqueId: true
- name: subject
externalId: $.actor.alternateId
type: String
indexed: true
- name: published
externalId: $.published
type: String
- name: version
externalId: $.version
type: String
- name: displayMessage
externalId: $.displayMessage
type: String
- name: severity
externalId: $.severity
type: String
- name: legacyEventType
externalId: $.legacyEventType
type: String
- name: outcomeResult
externalId: $.outcome.result
type: String
- name: outcomeReason
externalId: $.outcome.reason
type: String
- name: actorId
externalId: $.actor.id
type: String
- name: actorType
externalId: $.actor.type
type: String
- name: actorDisplayName
externalId: $.actor.displayName
type: String
- name: rawUserAgent
externalId: $.client.userAgent.rawUserAgent
type: String
- name: clientOS
externalId: $.client.userAgent.os
type: String
- name: clientId
externalId: $.client.id
type: String
- name: clientDevice
externalId: $.client.device
type: String
- name: clientZone
externalId: $.client.zone
type: String
TargetUserLifecycleDeactivate:
parent: user.lifecycle.deactivate
displayName: Target User Lifecycle Deactivate
externalId: $.target
pushExternalId: $.target
description: Target User Lifecycle Deactivate
pageSize: 100
pagesOrderedById: false
entityAlias: targetUserLifecycleDeactivate
attributes:
- name: id
externalId: $.id
type: String
indexed: true
uniqueId: true
- name: type
externalId: $.type
type: String
indexed: true
- name: alternateId
externalId: $.alternateId
type: String
- name: displayName
externalId: $.displayName
type: String
Delivery Method: The template is configured with deliveryMethod: "eventPush" and pushType: "Custom", indicating that it receives custom events through push delivery rather than polling for data.
Push Events Path: The pushEventsPath field uses JSON Path expressions to identify where events are located in the incoming payload. For example, $.data.events[*] extracts all events from the data.events array.
Push External IDs: Each attribute includes a pushExternalId field that uses JSON Path expressions to extract values from incoming event payloads. For example:
$.uuid extracts the event identifier$.actor.alternateId extracts the subject identifier$.outcome.result extracts nested event dataEntity Structure: The template defines parent-child relationships between events and their targets, allowing complex event structures to be modeled as related entities in the SGNL graph.
After pasting the template, configure the system-level settings:
Display Name: Enter a descriptive name for your Event Push System of Record
Description: Provide a description explaining the purpose and scope of this Event Push integration
Authentication Configuration: Configure authentication credentials if your Event Push implementation requires specific authentication beyond the push endpoint security
https://{clientName}.sgnlapis.cloud/events/custom/v1/{datasourceId}
{
"eventType": "com.okta.event_hook",
"eventId": "85b60edb-4263-4e13-993b-818e26201052",
"data": {
"events": [
{
"uuid": "f1d0b993-cc19-11ed-a688-db22c99ef6c4",
"published": "2023-03-26T21:05:32.159Z",
"eventType": "user.session.start",
"version": "0",
"displayMessage": "User login to Okta",
"severity": "INFO",
"client": {
"userAgent": {
"rawUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/111.0.0.0",
"os": "Mac OS X",
"browser": "CHROME"
},
"zone": "null",
"device": "Computer",
"id": null,
"ipAddress": "142.126.158.61"
},
"actor": {
"id": "00uz9fj5aT69fHVro1d6",
"type": "User",
"alternateId": "[email protected]",
"displayName": "Admin Name",
"detailEntry": null
},
"outcome": {
"result": "SUCCESS",
"reason": null
},
"target": [
{
"id": "lae42mkdc9i9cbw3U1d6",
"type": "AuthenticatorEnrollment",
"alternateId": "unknown",
"displayName": "Password",
"detailEntry": null
}
]
}
]
},
"eventTime": "2023-03-28T17:03:37.093Z",
"contentType": "application/json"
}
Prepare Test Request: Use a tool like Postman or curl to send events to your Event Push endpoint
Configure Headers: Set the following headers:
Content-Type: application/jsonAuthorization: Bearer {your-token} (if using bearer authentication)Send Event: POST the JSON payload to your Event Push endpoint:
curl -X POST \
https://events.sgnlapis.cloud/events/custom/v1/{your-datasource-id} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {your-token}' \
-d '{
"eventType": "test.event",
"eventId": "test-12345",
"data": {
"events": [
{
"uuid": "test-uuid-123",
"published": "2024-01-01T12:00:00.000Z",
"eventType": "test.event.type",
"displayMessage": "Test event for Event Push",
"actor": {
"alternateId": "[email protected]",
"displayName": "Test User"
}
}
]
},
"eventTime": "2024-01-01T12:00:00.000Z",
"contentType": "application/json"
}'
Verify Response: A successful request should return a 202 Accepted response, indicating that SGNL has accepted the event for processing
For Okta Event Hooks, you may need to handle verification events during the initial setup:
Event Push provides comprehensive event logging through Logs → Event Streams in the SGNL console
Use DataLens to explore your Event Push data:
Events Not Received: If SGNL is not receiving events, verify that event sources are configured with the correct SGNL endpoint URL and that network connectivity exists. Check firewall rules, proxy configurations, and DNS resolution between event sources and SGNL endpoints.
Authentication Failures: If events are being rejected due to authentication errors, verify that bearer tokens are valid and properly included in the Authorization header, or that JWT signature verification is configured correctly with accessible JWKS endpoints containing the appropriate public keys.
Event Format Errors: If events are being rejected due to format issues, verify that event sources are generating properly formatted JSON payloads. Check that required fields (unique ID, subject, event type) are present and correctly formatted.
Once your Event Push integration is successfully configured and receiving events, you can leverage real-time event data in dynamic SGNL policies that respond immediately to business and security events.
Real-Time Business Event Response: Use Event Push events to create policies that immediately respond to business process changes such as project updates, issue assignments, or workflow state changes that affect access decisions.
Security Event-Driven Access Control: Leverage security events from SIEM platforms, endpoint detection systems, or security tools to create policies that adjust access based on real-time security conditions, ensuring that access changes take effect immediately when security events occur.
Cross-System Coordination: Use Event Push to coordinate access changes across multiple systems in real-time. When an event occurs in one system, Event Push can immediately update the SGNL graph, triggering actions in related systems and changing the outcome of policy decisions.
Action Triggering: Use Event Push events to trigger SGNL Actions that can propagate access changes to downstream systems, creating a comprehensive real-time access orchestration workflow.
For comprehensive guidance on creating policies with Event Push data, refer to the SGNL Policy Management documentation. For advanced entity modeling and relationship configuration, review the Entities and Relationships guide.