Webhook Management

Benefits

cidaas offers the possibility to inform about a variety of events, such as ACCOUNT_CREATED, LOGIN, ACCOUNT_MODIFIED. These events are implemented via webhooks.

The event-driven software architecture of cidaas triggers these webhooks asynchronously immediately after the event occurs to ensure high performance.

Besides the direct integration of your systems during authentication and registration you have the possibility that your systems can react very fast to changes of your user data and not only technically, but also execute business actions.

Configuration

You can define webhooks as an administrator in the Admin Dashboard or, if necessary, follow the Infrastructure as a code approach and set up the Webhook setups using the cidaas APIs.

Setup via API

Configure your webhooks with the cidaas webhook APIs

Implement a webhook

Preliminary considerations

You implement a webhook as a web service that is secured accordingly. You can secure it with OAuth2 for authentication.
You define which cidaas events your webhook consumes in the webhook setup.
Your webhook service will be called immediately when one of the events you registered your service for occurs.
The information given to the web service by cidaas is limited. They are used to allow you to retrieve additional data from cidaas if necessary to implement the intended use case.
In order to get this information from cidaas, you use an app that defines exactly the access you need.
Your web service always acknowledges successful processing with http status 200 (OK).
If a problem occurs during the execution of your webhook service and the service responds with an http status != 200, then cidaas will log the error and execute the service again. If it is a permanent error, the service will not be executed again.
Your service should be designed to be performant, if the execution time is too long it will not wait for the service response after a specified execution time with a timeout.
Webhooks are called asynchronously
- for example, if your webhook service is not available, your webhook service will consume the cidaas event after availability
- this also means that webhooks do not block processing in cidaas

How the webhook gets called

The following flowchart illustrates how a webhook is triggered when a user account is modified:

Flow Steps:

Change User Account: User account is modified (e.g., update email, name, or profile data)
ACCOUNT_MODIFIED Event Triggered: cidaas automatically generates an ACCOUNT_MODIFIED event
Webhook Setup Check: cidaas checks if any webhook setup contains ACCOUNT_MODIFIED in its event list
POST Request: If the webhook setup contains ACCOUNT_MODIFIED, cidaas sends a POST request to the external webhook URL with the event payload
Immediate Response: Your external webhook service should return HTTP 200 OK immediately upon receiving the event to prevent timeouts
Asynchronous Processing: After returning HTTP 200, your webhook processes the ACCOUNT_MODIFIED event asynchronously
Continue: If no webhook setup contains ACCOUNT_MODIFIED, the process continues without calling any webhook

Best Practice: Return HTTP 200 OK immediately after receiving the webhook request, then process the event asynchronously. This prevents timeouts for long-running operations and ensures cidaas doesn't retry the webhook call.

Webhook Request

The Webhook service is executed as a POST call, passing the following information depending on the event.

The webhookObj is a standardized event payload that provides context about what happened, when, who triggered it, on which tenant, and what was affected. The only dynamic part is the metaData, which varies depending on the specific event type (eventtype).

📦 Structure of `webhookObj`

{
    "webhookObj": {
        "eventtype": "APP_MODIFIED",
        "createdTime": "2025-01-15T10:30:00.000Z",
        "client_id": "cc2dd2ed-57f1-4a5d-85f2-e868c98db3d7",
        "tenantKey": "cidaas-your-tenant-name-test",
        "actorId": "admin-user-id-123",
        "metaData": {
            "client_id": "modified-app-client-id"
        },
        "objectId": "app-id-456",
        "objectType": "apps"
    }
}

🧾 Field-by-Field Explanation

Field	Type	Description	Example
`eventtype`	string	The type of event that occurred	`"APP_MODIFIED"`, `"ACCOUNT_MODIFIED"`, `"LOGIN_WITH_CIDAAS"`
`createdTime`	string (ISO 8601)	The exact time when the event was created or triggered	`"2025-01-15T10:30:00.000Z"`
`client_id`	string	The identifier of the client that triggered the event (e.g., admin tool, API integration, or automated system)	`"cc2dd2ed-57f1-4a5d-85f2-e868c98db3d7"`
`tenantKey`	string	Specifies the tenant (customer or environment) the event belongs to. Useful in multi-tenant systems	`"cidaas-your-tenant-name-test"`
`actorId`	string	The ID of the user or service that performed the action	`"admin-user-id-123"`
`metaData`	object	A flexible field that holds event-specific information. Structure and content depend on the `eventtype`	For `"APP_MODIFIED"`: `{"client_id": "modified-app-client-id"}`
`objectId`	string	The ID of the main object affected by the event. Often, but not always, duplicates information in `metaData`	`"app-id-456"`
`objectType`	string	Specifies what kind of object the event was about	`"apps"`, `"users"`, `"usergroups"`

Webhook Response

Your webhook service must return HTTP 200 (OK) to indicate successful processing. This is the only status code that cidaas considers as successful completion.

Important: All other HTTP status codes (e.g., 400, 401, 404, 417, 500) will be treated as failures and cidaas will automatically retry the webhook call. If the error persists, cidaas will continue retrying until it determines the error is permanent, at which point retries will stop.

Successful Response (HTTP 200):

Your webhook should return HTTP 200 with an optional response body:

{
  "status": 200
}

Or with additional data:

{
  "status": 200,
  "data": {
    "message": "Webhook processed successfully"
  }
}

The response body (if provided) is stored in the webhook status and can be viewed in the cidaas Admin Dashboard or by using the webhook API.

Retry Behavior:

HTTP 200: Webhook processed successfully, no retry
Any other status code: Webhook failed, cidaas will retry automatically
Permanent errors: After multiple retry attempts, cidaas will stop retrying

Best Practice: Ensure your webhook service is well-tested and returns HTTP 200 only when processing is truly successful. For temporary issues, return HTTP 200 and handle the error internally, or return a non-200 status if you want cidaas to retry.

Available webhooks

cidaas provides a comprehensive set of webhook events that you can subscribe to for real-time notifications about various activities in your system.

📋 Interactive Webhook Events Table

For a complete, searchable, and interactive reference of all available webhook events with full JSON payload examples, please visit our dedicated webhook events table:

🚀 View Complete Webhook Events Table

🎯 Key Features of the Interactive Table:

🔍 Search & Filter: Find events by name, type, or description
📋 Complete JSON Payloads: Click "View Full Payload" to see the exact JSON structure
📱 Responsive Design: Works perfectly on all devices
📋 Copy to Clipboard: One-click copying of JSON payloads for development
🎨 Professional Interface: Clean, modern design with hover effects

📊 Event Categories:

The webhook events cover the following main categories:

👤 User Management: Account creation, login, profile updates, verification
🛠️ App & System Management: App settings, scopes, templates, webhooks
👥 Group & Role Management: Group operations, user assignments, role changes
🔐 Security & Authentication: Login failures, token operations, security events
📱 Communication: SMS, email, push notifications, IVR
✅ Verification: Physical verification, ID validation, consent management
💳 Business Operations: Checkout sessions, subscriptions, payments

💡 Quick Examples:

User Account Created:

{
  "eventtype": "ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY",
  "sub": "2ecb51cb-ac07-4f1f-98a7-fa61f512918f",
  "createdTime": "2025-10-01T08:23:47.451+0000",
  "client_id": "cc2dd2ed-57f1-4a5d-85f2-e868c98db3d7",
  "tenantKey": "cidaas-your-tenant-name-test",
  "userId": "2ecb51cb-ac07-4f1f-98a7-fa61f512918f",
  "actorId": "2ecb51cb-ac07-4f1f-98a7-fa61f512918f",
  "metaData": {
    "provider": "self"
  },
  "objectId": "2ecb51cb-ac07-4f1f-98a7-fa61f512918f",
  "objectType": "users"
}

App Created:

{
  "eventtype": "APP_CREATED",
  "sub": "admin-user-id-123",
  "createdTime": "2025-10-01T08:23:47.451+0000",
  "client_id": "cc2dd2ed-57f1-4a5d-85f2-e868c98db3d7",
  "tenantKey": "cidaas-your-tenant-name-test",
  "userId": "admin-user-id-123",
  "actorId": "admin-user-id-123",
  "metaData": {
    "client_id": "new-app-client-id"
  },
  "objectId": "new-app-id-456",
  "objectType": "apps"
}

Need Support?

Please contact us directly on our support page.

Benefits​

Configuration​

Setup via API​

Implement a webhook​

Preliminary considerations​

How the webhook gets called​

Webhook Request​

📦 Structure of webhookObj​

🧾 Field-by-Field Explanation​

Webhook Response​

Available webhooks​

📋 Interactive Webhook Events Table​

🎯 Key Features of the Interactive Table:​

📊 Event Categories:​

💡 Quick Examples:​

Need Support?​