Identity Webhooks

Webhooks enable your applications to receive real-time notifications when events occur in your identity and access management systems. This eliminates the need for polling and ensures your systems stay synchronized with user provisioning, authentication, and access control changes across all integrated platforms.

Unizo normalizes webhook events from Okta, Auth0, Azure AD, OneLogin, and other identity providers into a consistent format. This means you write your webhook handler once and it works with all supported platforms.

Webhook Configuration

To set up webhooks for your integration, visit the Unizo Console Webhooks section for step-by-step configuration guide.

Supported Event Types

These are the event types currently supported by Unizo's Identity webhooks. The list keeps growing as we add support for more events across different platforms.

Event Type	Description	Trigger Conditions
user:created	A new user has been created	User account creation via UI, API, or sync
user:updated	User profile information has been modified	Profile updates, attribute changes, or status updates
user:deleted	A user account has been deleted	User deletion or deactivation
group:created	A new group has been created	Group creation via UI or API
group:updated	Group information has been modified	Group name, description, or membership changes
group:deleted	A group has been deleted	Group removal from the system
authentication:success	Successful authentication attempt	User successfully logs in
authentication:failed	Failed authentication attempt	Invalid credentials or blocked access
role:assigned	Role assigned to a user	Role assignment via UI or API
role:revoked	Role removed from a user	Role revocation via UI or API

Webhook Security

All webhooks from Unizo include security headers to verify authenticity:

Headers

Header	Description
`x-unizo-event-type`	The type of event that triggered the webhook
`x-unizo-signature`	HMAC SHA-256 signature for request validation
`x-unizo-timestamp`	Unix timestamp when the event was sent
`x-unizo-delivery-id`	Unique identifier for this webhook delivery

Signature Verification

Verify the authenticity of incoming webhooks using HMAC SHA-256:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Event Details

User Events

Event Type	Description	Trigger Conditions
user:created	A new user has been created	User account creation via UI, API, or sync
user:updated	User profile information has been modified	Profile updates, attribute changes, or status updates
user:deleted	A user account has been deleted	User deletion or deactivation

User Created

`user:created`

Triggered when a new user account is created in the identity system

POSThttps://api.yourapp.com/webhooks/unizo/identity

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/identity - Route by category (identity, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: user:created
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`user.id`	string	Yes	Unique user identifier
`user.email`	string	Yes	User's email address
`user.username`	string	No	User's username
`user.firstName`	string	Yes	User's first name
`user.lastName`	string	Yes	User's last name
`user.status`	string	Yes	User status: active, pending, suspended
`user.createdDateTime`	string	Yes	ISO 8601 timestamp
`user.createdBy`	object	No	User who created this account
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "user:created",
  "version": "1.0.0",
  "user": {
    "id": "user-123456",
    "email": "john.doe@example.com",
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "status": "active",
    "createdDateTime": "2024-01-15T14:00:00Z",
    "createdBy": {
      "id": "admin-789",
      "email": "admin@example.com"
    }
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Okta Production",
    "provider": "okta"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

User Updated

`user:updated`

Triggered when user profile information is modified

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: user:updated
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`user.id`	string	Yes	Unique user identifier
`user.email`	string	Yes	User's email address
`user.changes`	object	Yes	Object containing changed fields
`user.updatedDateTime`	string	Yes	ISO 8601 timestamp
`user.updatedBy`	object	No	User who made the update
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "user:updated",
  "version": "1.0.0",
  "user": {
    "id": "user-123456",
    "email": "john.doe@example.com",
    "changes": {
      "lastName": {
        "from": "Doe",
        "to": "Smith"
      },
      "department": {
        "from": "Engineering",
        "to": "Product"
      }
    },
    "updatedDateTime": "2024-01-15T15:00:00Z",
    "updatedBy": {
      "id": "admin-789",
      "email": "admin@example.com"
    }
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Okta Production",
    "provider": "okta"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

User Deleted

`user:deleted`

Triggered when a user account is deleted or deactivated

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: user:deleted
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`user.id`	string	Yes	Unique user identifier
`user.email`	string	Yes	User's email address
`user.deletedDateTime`	string	Yes	ISO 8601 timestamp
`user.deletedBy`	object	No	User who deleted this account
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "user:deleted",
  "version": "1.0.0",
  "user": {
    "id": "user-123456",
    "email": "john.doe@example.com",
    "deletedDateTime": "2024-01-15T16:00:00Z",
    "deletedBy": {
      "id": "admin-789",
      "email": "admin@example.com"
    }
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Okta Production",
    "provider": "okta"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Group Events

Event Type	Description	Trigger Conditions
group:created	A new group has been created	Group creation via UI or API
group:updated	Group information has been modified	Group name, description, or membership changes
group:deleted	A group has been deleted	Group removal from the system

Group Created

`group:created`

Triggered when a new group is created in the identity system

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: group:created
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`group.id`	string	Yes	Unique group identifier
`group.name`	string	Yes	Group name
`group.description`	string	No	Group description
`group.type`	string	Yes	Group type: security, distribution
`group.createdDateTime`	string	Yes	ISO 8601 timestamp
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "group:created",
  "version": "1.0.0",
  "group": {
    "id": "group-789",
    "name": "Engineering Team",
    "description": "All engineering department members",
    "type": "security",
    "createdDateTime": "2024-01-15T14:00:00Z"
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Azure AD Production",
    "provider": "azure_ad"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Authentication Events

Event Type	Description	Trigger Conditions
authentication:success	Successful authentication attempt	User successfully logs in
authentication:failed	Failed authentication attempt	Invalid credentials or blocked access

Authentication Success

`authentication:success`

Triggered when a user successfully authenticates

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: authentication:success
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`user.id`	string	Yes	User identifier
`user.email`	string	Yes	User's email address
`authentication.method`	string	Yes	Authentication method used
`authentication.ipAddress`	string	Yes	Client IP address
`authentication.userAgent`	string	No	Client user agent
`authentication.timestamp`	string	Yes	ISO 8601 timestamp
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "authentication:success",
  "version": "1.0.0",
  "user": {
    "id": "user-123456",
    "email": "john.doe@example.com"
  },
  "authentication": {
    "method": "password",
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "timestamp": "2024-01-15T14:00:00Z"
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Auth0 Production",
    "provider": "auth0"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Role Events

Event Type	Description	Trigger Conditions
role:assigned	Role assigned to a user	Role assignment via UI or API
role:revoked	Role removed from a user	Role revocation via UI or API

Role Assigned

`role:assigned`

Triggered when a role is assigned to a user

POSThttps://api.yourapp.com/webhooks/unizo/scm

Best Practice: Use a dedicated webhook endpoint that can handle multiple event types. You have two architectural options:
• Single endpoint: https://api.yourapp.com/webhooks/unizo - Route all events to one handler
• Category-based endpoints: https://api.yourapp.com/webhooks/unizo/scm - Route by category (scm, ticketing, etc.) for microservices architecture

Headers

Name	Type	Required	Description
`Content-Type`	string	Yes	Always application/json
`x-unizo-event-type`	string	Yes	Event type: role:assigned
`x-unizo-webhook-id`	string	Yes	Unique webhook configuration ID
`x-unizo-delivery-id`	string	Yes	Unique delivery ID for idempotency
`x-unizo-signature`	string	Yes	HMAC SHA-256 signature

Request Body Schema

Property	Type	Required	Description
`type`	string	Yes	Event type identifier
`version`	string	Yes	Webhook payload version
`user.id`	string	Yes	User identifier
`user.email`	string	Yes	User's email address
`role.id`	string	Yes	Role identifier
`role.name`	string	Yes	Role name
`role.permissions`	array	No	List of permissions
`assignedDateTime`	string	Yes	ISO 8601 timestamp
`assignedBy`	object	No	User who assigned the role
`integration`	object	Yes	Integration details

Example Payload

{
  "type": "role:assigned",
  "version": "1.0.0",
  "user": {
    "id": "user-123456",
    "email": "john.doe@example.com"
  },
  "role": {
    "id": "role-456",
    "name": "Admin",
    "permissions": [
      "read",
      "write",
      "delete"
    ]
  },
  "assignedDateTime": "2024-01-15T14:00:00Z",
  "assignedBy": {
    "id": "admin-789",
    "email": "admin@example.com"
  },
  "integration": {
    "type": "IDENTITY",
    "id": "int_123456",
    "name": "Okta Production",
    "provider": "okta"
  }
}

Response

`200 OK`	Webhook processed successfully
`400 Bad Request`	Invalid webhook payload
`401 Unauthorized`	Invalid or missing signature

Webhook Delivery & Retries

Unizo implements automatic retry logic for failed webhook deliveries:

Initial Delivery: Immediate
First Retry: After 1 minute
Second Retry: After 5 minutes
Third Retry: After 15 minutes
Final Retry: After 1 hour

Webhooks are considered failed if:

Your endpoint returns a non-2xx status code
Connection timeout (30 seconds)
SSL/TLS errors

Best Practices

1. Idempotency

Idempotent Webhook Handler

async function handleWebhook(request) {
const deliveryId = request.headers['x-unizo-delivery-id'];

// Check if already processed
if (await isProcessed(deliveryId)) {
  return { status: 200, message: 'Already processed' };
}

// Process webhook
await processWebhook(request.body);

// Mark as processed
await markProcessed(deliveryId);

return { status: 200 };
}

2. Async Processing

Asynchronous Processing

app.post('/webhooks/identity', (req, res) => {
// Validate signature
if (!verifySignature(req)) {
  return res.status(401).send('Invalid signature');
}

// Queue for processing
identityQueue.add(req.body);

// Return immediately
res.status(200).send('OK');
});

3. Error Handling

Comprehensive Error Handling

async function processWebhook(payload) {
try {
  switch (payload.type) {
    case 'user:created':
      await handleUserCreated(payload);
      break;
    case 'role:assigned':
      await handleRoleAssigned(payload);
      break;
    default:
      logger.warn(`Unknown webhook type: ${payload.type}`);
  }
} catch (error) {
  logger.error('Webhook processing failed', {
    error: error.message,
    payload,
    stack: error.stack
  });
  throw error;
}
}

Need Help?

For webhook-related support:

Contact support at support@unizo.ai

Supported Event Types​

Webhook Security

Headers

Signature Verification

Event Details​

User Events​

User Created

user:created

Headers

Request Body Schema

Example Payload

Response

User Updated

user:updated

Headers

Request Body Schema

Example Payload

Response

User Deleted

user:deleted

Headers

Request Body Schema

Example Payload

Response

Group Events​

Group Created

group:created

Headers

Request Body Schema

Example Payload

Response

Authentication Events​

Authentication Success

authentication:success

Headers

Request Body Schema

Example Payload

Response

Role Events​

Role Assigned

role:assigned

Headers

Request Body Schema

Example Payload

Response

Webhook Delivery & Retries​

Best Practices​

1. Idempotency​

Idempotent Webhook Handler

2. Async Processing​

Asynchronous Processing

3. Error Handling​

Comprehensive Error Handling

Need Help?​

Supported Event Types

Event Details

User Events

`user:created`

`user:updated`

`user:deleted`

Group Events

`group:created`

Authentication Events

`authentication:success`

Role Events

`role:assigned`

Webhook Delivery & Retries

Best Practices

1. Idempotency

2. Async Processing

3. Error Handling

Need Help?