Webhook Event Catalog

Use the event-types endpoint for the identifiers supported by the running deployment. For the maintained static payload reference, see Webhook Events Reference.

Event Types

GET /api/organizations/:org_slug/webhooks/event-types

Get a list of all available webhook event types with descriptions and categories.

Authentication: Required (Organization Management JWT)

Permissions: Organization owner or admin

Path Parameters:

Query Parameters: None

Request Headers:

Authorization: Bearer {jwt_token}

Example Request:

curl -X GET https://sso.example.com/api/organizations/acme-corp/webhooks/event-types \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response (200 OK):

[
  {
    "value": "user.signup.success",
    "label": "USER SIGNUP SUCCESS",
    "category": "User Management"
  },
  {
    "value": "user.login.success",
    "label": "USER LOGIN SUCCESS",
    "category": "User Management"
  },
  {
    "value": "user.login.failed",
    "label": "USER LOGIN FAILED",
    "category": "User Management"
  },
  {
    "value": "user.logout",
    "label": "USER LOGOUT",
    "category": "User Management"
  },
  {
    "value": "user.mfa.enabled",
    "label": "USER MFA ENABLED",
    "category": "User Management"
  }
]

Response Fields:

• value (string): Event type identifier (use this in webhook subscription)
• label (string): Human-readable event name
• category (string): Event category

Event Categories:

• User Management
• Service Management
• Organization Management
• Plan Management
• Subscription Management
• Invitation Management
• Security
• API Keys
• Custom Domains
• Branding

Error Responses:

• 401 Unauthorized: Missing or invalid JWT token
• 403 Forbidden: User is not an admin or owner
• 404 Not Found: Organization not found

Available Event Types

Webhooks can subscribe to the following event types:

User Management

Lifecycle Events:

• user.signup.success - New user account created
• user.login.success - Successful user authentication
• user.login.failed - Failed authentication attempt
• user.logout - User logged out

MFA Events:

• user.mfa.enabled - User enabled MFA
• user.mfa.disabled - User disabled MFA
• user.mfa.verify.success - Successful MFA verification
• user.mfa.verify.failed - Failed MFA verification

Administrative Actions:

• user.invited - User invited to organization
• user.joined - User accepted invitation
• user.removed - User removed from organization
• user.role_updated - User role changed

Service Management

• service.created - New service created
• service.updated - Service details updated
• service.deleted - Service deleted
• service.oauth_credentials.updated - OAuth credentials updated

Organization Management

• organization.updated - Organization details updated
• organization.smtp.configured - SMTP settings configured
• organization.smtp.removed - SMTP settings removed

Plan Management

• plan.created - New subscription plan created
• plan.updated - Plan updated
• plan.deleted - Plan deleted

Subscription Management

• subscription.created - User subscribed to plan
• subscription.updated - Subscription modified
• subscription.canceled - Subscription canceled

Invitation Management

• invitation.accepted - Invitation accepted
• invitation.declined - Invitation declined
• invitation.expired - Invitation expired
• invitation.revoked - Invitation revoked

Security Events

• security.mfa.enabled - Organization-level MFA enabled
• security.mfa.disabled - Organization-level MFA disabled
• security.password.changed - Password changed

API Key Management

• api_key.created - API key created
• api_key.deleted - API key deleted

Custom Domains & Branding

• domain.set - Custom domain set
• domain.verified - Custom domain verified
• domain.deleted - Custom domain deleted
• branding.updated - Branding settings updated

Webhook Payload Structure

All webhook deliveries follow a consistent payload structure:

{
  "event": "user.login.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "actor_user_id": "user-uuid",
  "actor_email": "user@example.com",
  "target_type": "user",
  "target_id": "user-uuid",
  "data": {
    "service_id": "service-uuid",
    "provider": "github",
    "custom_field": "value"
  }
}

Common Fields:

• event (string): Event type that triggered the webhook
• timestamp (string): ISO 8601 timestamp of event occurrence
• organization_id (string): Organization ID (if applicable)
• actor_user_id (string): User ID who triggered the event (if applicable)
• actor_email (string): Email of user who triggered the event (if applicable)
• target_type (string): Type of resource affected (e.g., “user”, “service”, “organization”)
• target_id (string): ID of the affected resource
• data (object): Event-specific additional data

Example Payloads

User Signup:

{
  "event": "user.signup.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-123",
  "actor_user_id": "user-456",
  "actor_email": "newuser@example.com",
  "target_type": "user",
  "target_id": "user-456",
  "data": {
    "provider": "google",
    "service_id": "service-789"
  }
}

User Login:

{
  "event": "user.login.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-123",
  "actor_user_id": "user-456",
  "actor_email": "user@example.com",
  "target_type": "user",
  "target_id": "user-456",
  "data": {
    "provider": "github",
    "service_id": "service-789"
  }
}

MFA Enabled:

{
  "event": "user.mfa.enabled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-123",
  "actor_user_id": "user-456",
  "actor_email": "user@example.com",
  "target_type": "user",
  "target_id": "user-456",
  "data": {
    "method": "totp",
    "backup_codes_count": 10
  }
}

Service Created:

{
  "event": "service.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-123",
  "actor_user_id": "admin-789",
  "actor_email": "admin@acme.com",
  "target_type": "service",
  "target_id": "service-456",
  "data": {
    "service_name": "Mobile App",
    "service_slug": "mobile-app",
    "service_type": "mobile"
  }
}