Tracking User Updates
Overview
Tracking user updates is essential for various use cases such as data analytics, user activity monitoring, and access control adjustments. Descope provides two primary methods to track user updates effectively:
- Search Users API - Retrieve users based on their creation or modification timestamps.
- Audit Webhooks - Stream real-time audit events for user actions such as creation, modification, and deletion.
This guide will explore both approaches, their use cases, and how to implement them in your system.
Method 1: Using the Search Users API
The Search Users API allows you to filter users based on various attributes, including their creation or last modification timestamps. This is useful when you need to:
- Track newly created users over a specific period.
- Monitor modifications to existing users.
- Maintain an up-to-date user cache for analytics or reporting.
API Endpoint
Endpoint: POST /v2/mgmt/user/search
. The docs are here.
Search Users API Request Body
Below is an example of the request body:
Search Users API Parameters
The API provides the following parameters to filter users:
Parameter | Type | Description |
---|---|---|
fromCreatedTime | int | Include users created on or after this time (Unix epoch seconds). |
toCreatedTime | int | Include users created on or before this time (Unix epoch seconds). |
fromModifiedTime | int | Include users modified on or after this time (Unix epoch seconds). |
toModifiedTime | int | Include users modified on or before this time (Unix epoch seconds). |
Example Use Case: User Data Synchronization
If you store user data in a database and need to periodically update it, you can use the fromModifiedTime
parameter to fetch all users modified since the last synchronization timestamp.
Example API Call
This request will return all users who were updated on or after Unix epoch time 1700000000.
For more details, visit the Search Users API documentation.
Method 2: Using Audit Webhooks for Event-Based Updates
The Audit Webhook feature allows you to receive events when users are created, modified, or deleted. Note that these events are not delivered in real-time and include an internal throttling mechanism to manage system load. This is useful when:
- You need to track user changes without polling the Search Users API.
- Your system relies on event-driven architectures.
- You want to log or trigger actions based on user modifications.
Setting Up an Audit Webhook
- Navigate to the Connectors page and Select the "Audit Webhook".
- Configure the following:
- Name: The Audit Webhook instance name.
- Base URL: Your API endpoint to receive audit events.
- Authentication Type: (Optional) Based on your implementation, choose one from the following - None, Bearer Token, API Key, Basic or OAuth2.0.
- Event Type: Select "Stream filtered audit events only", Select "Action" as the key, "Includes" as the operator, then add
User Created
,User Modified
, andUser Deleted
.
- Test and save the Audit Webhook instance.
Example Audit Event Payload
When a user is modified, an event like the following is sent to your audit webhook endpoint:
For more information about available events, please review the Audit Events article.
Example Use Case: Keeping an External Database in Sync
If your system needs to track user record modifications, an audit webhook can push changes to your API, which updates your database. Note that due to the throttling mechanism, there may be a delay between when a change occurs and when your system receives the event.
Choosing the Right Approach
Use Case | Recommended Method |
---|---|
Periodic batch updates of users | Search Users API |
Event-based tracking of user changes | Audit Webhook |
Hybrid approach (initial sync + event-based updates) | Both |
Hybrid Approach: Combining API & Webhooks
For an optimal setup:
- Use the Search Users API to initially populate your user database.
- Set up an Audit Webhook to capture user changes and keep your data updated.
- Periodically re-sync using the API as a fallback in case of webhook failures or to catch any missed events due to throttling.
Conclusion
Tracking user updates is crucial for maintaining accurate records and responding to changes efficiently. By leveraging Descope's Search Users API and Audit Webhooks, you can implement a reliable and scalable approach to user monitoring, whether for data analytics, security audits, or operational needs.