Webhooks and Event Notifications

Relevant source files

The following files were used as context for generating this wiki page:

• controllers/webhook.go
• object/webhook.go
• object/webhook_util.go
• object/record.go
• web/src/WebhookEditPage.js
• web/src/backend/WebhookBackend.js
• routers/router.go

Webhooks in Casdoor allow external applications to build integrations by subscribing to specific platform events. When a subscribed event occurs (such as user signup, login, or logout), Casdoor sends an HTTP POST request containing a JSON payload to a configured URL. This system enables real-time synchronization with external databases, issue trackers, or custom automation workflows.

The system is built on a subscription model where administrators define the target URL, the HTTP method, and the specific events that should trigger the notification. It supports advanced features such as user field extension, where specific user profile information can be injected into the event payload.

Sources: web/src/TourConfig.js, object/webhook.go:31-48

System Architecture and Data Model

The webhook system consists of a management interface (Frontend), API controllers for CRUD operations, and a backend engine that processes events and dispatches notifications.

Webhook Data Structure

The Webhook object defines how and when a notification is sent.

Field	Type	Description
Owner	string	The owner of the webhook (typically "admin").
Name	string	Unique identifier for the webhook.
Organization	string	The organization context for the webhook.
Url	string	The target endpoint to receive the notification.
Method	string	HTTP method (POST, GET, PUT, DELETE).
ContentType	string	MIME type (e.g., application/json).
Events	[]string	List of trigger events (e.g., signup, login).
IsUserExtended	bool	Whether to include detailed user data in the payload.
IsEnabled	bool	Current operational status of the webhook.

Sources: object/webhook.go:31-48, web/src/WebhookEditPage.js:154-250

Event Workflow

The following diagram illustrates the lifecycle of an event notification from the initial action to the external endpoint delivery.

The system generates a Record for most API actions. If webhooks are active and match the event type, the SendWebhooks function iterates through valid subscriptions.

Sources: object/record.go:132-152, object/record.go:216-261

Execution Logic

The core logic for dispatching notifications resides in the object package. When an action occurs, the system evaluates all defined webhooks.

Webhook Filtering

Webhooks are filtered based on three primary criteria:

1. Enablement: The IsEnabled flag must be true.
2. Organization Scope: If SingleOrgOnly is true, the organization of the event must match the webhook's organization.
3. Event Match: The action (e.g., update-user) must be present in the webhook's Events array.

Sources: object/record.go:167-195

Request Dispatching

The sendWebhook function constructs the HTTP request. It sets headers (including custom headers defined in the webhook configuration) and serializes the payload.

func sendWebhook(webhook *Webhook, record *casvisorsdk.Record, extendedUser *User) (int, string, error) {
	client := &http.Client{}
    // ... logic to build payload ...
	req, err := http.NewRequest(webhook.Method, webhook.Url, body)
	req.Header.Set("Content-Type", webhook.ContentType)
	for _, header := range webhook.Headers {
		req.Header.Set(header.Name, header.Value)
	}
	resp, err := client.Do(req)
    // ...
}

Sources: object/webhook_util.go:26-70

API Endpoints

The system provides several management endpoints handled by ApiController and routed through routers/router.go.

Endpoint	Method	Description
/api/get-webhooks	GET	Retrieves a list of webhooks for an owner/org.
/api/get-webhook	GET	Retrieves details for a specific webhook.
/api/add-webhook	POST	Creates a new webhook configuration.
/api/update-webhook	POST	Updates an existing webhook.
/api/delete-webhook	POST	Removes a webhook configuration.

Sources: controllers/webhook.go:26-140, routers/router.go:149-153

User Data Extension

A specialized feature of Casdoor webhooks is the ability to include "Extended User" information. If IsUserExtended is enabled, the webhook payload includes a representation of the user involved in the event.

Administrators can configure TokenFields to specify which user attributes (e.g., email, displayName, avatar) should be included in the JSON body. This avoids the need for the receiving application to call back to the Casdoor API to fetch user details.

Sources: object/webhook_util.go:31-50, web/src/WebhookEditPage.js:220-230

Monitoring and Logging

Every webhook attempt is recorded in the system logs. If a webhook fails (returns a non-200 status code), a specific record is added to the database with the Action set to send-webhook, allowing administrators to debug integration issues by viewing the response body and status code.

Sources: object/record.go:197-230

Conclusion

The Webhooks and Event Notifications system provides a robust integration layer for Casdoor. By leveraging the internal recording mechanism, it ensures that external systems stay in sync with identity events while providing granular control over data privacy via field filtering and organization scoping.

Sources: web/src/TourConfig.js, object/record.go:232-280