User Management Syncing via Webhooks

Keeping user information up to date across multiple systems can be challenging. With Firstup’s Webhook API, you can automatically sync user profile changes (such as role updates, name changes, or deactivations) with external HRIS platforms, Active Directory, or an employee dashboard.

Prerequisites

Before setting up user management syncing, ensure that:

1. You have a publicly accessible endpoint that can receive webhook events (e.g., your HR system’s API).
2. You have API access to register webhooks via the POST /v2/webhooks/subscriptions endpoint.
3. You have permission to fetch user details using the GET /scim/v2/users/{userId} endpoint if you need additional data.

Step 1: Creating the Webhook Subscription

To receive notifications when user data changes, register a webhook that listens for user.updated and user.deactivated events.

Example Request to Create a Webhook

POST /v2/webhooks/subscriptions
{
  "name": "User Management Webhook",
  "url": "https://your-hr-system.com/api/firstup-webhook",
  "events": ["user.updated", "user.deactivated"],
  "active": true
}

Step 2: Handling the Webhook Event

Once registered, your external system will receive a POST request from Firstup whenever a user’s profile is updated or deactivated.

Example Webhook Payload (User Profile Update)

{
  "event": "user.updated",
  "timestamp": "2025-03-26T12:34:56Z",
  "data": {
    "userId": "98765",
    "userName": "john.doe",
    "email": "john.doe@example.com",
    "name": {
      "givenName": "John",
      "familyName": "Doe"
    },
    "roles": ["admin"],
    "active": true,
    "updatedAt": "2025-03-26T12:30:00Z"
  }
}

Your HR or directory system should be able to parse this payload and update the employee record accordingly.

Example Webhook Payload (User Deactivation)

{
  "event": "user.deactivated",
  "timestamp": "2025-03-26T12:35:00Z",
  "data": {
    "userId": "98765",
    "userName": "john.doe",
    "email": "john.doe@example.com",
    "active": false,
    "deactivatedAt": "2025-03-26T12:34:00Z"
  }
}

If a user is deactivated, your system should remove or disable the user’s access in external tools like an HR system, CRM, or IT management system.

Step 3: Fetching Additional User Details (Optional)

If your system needs more information about the user, you can retrieve their full profile using the GET /scim/v2/users/{userId} endpoint.

Endpoint

Example Request to Fetch User Details

GET /scim/v2/users/98765
Authorization: Bearer YOUR_ACCESS_TOKEN

Example Response

{
  "id": "98765",
  "userName": "john.doe",
  "email": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "roles": ["admin"],
  "active": false,
  "deactivatedAt": "2025-03-26T12:34:00Z"
}