Webhook Events Reference

Complete reference of all webhook event types supported by AuthOS.

Webhook Payload Format

All webhook payloads follow a unified structure that provides context about the event, the actor who triggered it, and the target resource.

{
  "event": "user.login.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "actor_user_id": "user-uuid-actor",
  "actor_email": "admin@example.com",
  "target_type": "user",
  "target_id": "user-uuid-target",
  "data": {
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

Top-Level Fields

Field	Type	Description
`event`	`string`	The event type identifier (e.g., `user.joined`).
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred.
`organization_id`	`string`	UUID of the organization associated with the event.
`actor_user_id`	`string`	(Optional) UUID of the user who performed the action.
`actor_email`	`string`	(Optional) Email of the user who performed the action.
`target_type`	`string`	(Optional) Type of resource affected (e.g., `user`, `service`).
`target_id`	`string`	(Optional) UUID of the affected resource.
`data`	`object`	(Optional) Map of additional event-specific details.

Event Index

User Lifecycle

user.signup.success - New user registration complete
user.login.success - Successful login
user.login.failed - Failed login attempt
user.logout - User session terminated
user.anonymized - User data anonymized (GDPR)

Multi-Factor Auth (MFA)

user.mfa.enabled - MFA set up for account
user.mfa.disabled - MFA removed from account
user.mfa.verify.success - Successful MFA challenge
user.mfa.verify.failed - Failed MFA challenge

Organization & Team

user.invited - Member invitation sent
user.joined - Member accepted invitation or provisioned
user.removed - Member removed from organization
user.role_updated - Member role changed
organization.updated - Org settings changed
organization.smtp.configured - SMTP settings updated
organization.smtp.removed - SMTP settings deleted

Services & Plans

service.created - New application service created
service.updated - Service configuration updated
service.deleted - Service removed
service.oauth_credentials.updated - BYOO credentials changed
plan.created - New subscription plan created
plan.updated - Plan details changed
plan.deleted - Plan removed

Subscriptions & Billing

subscription.created - User subscribed to a plan
subscription.updated - Subscription modified or renewed
subscription.canceled - Subscription canceled

Invitations

invitation.accepted - Invitation token used successfully
invitation.declined - Invitation explicitly rejected
invitation.expired - Invitation token no longer valid
invitation.revoked - Invitation cancelled by admin

Security & Governance

security.mfa.enabled - Admin-enforced MFA enable
security.mfa.disabled - Admin-enforced MFA disable
security.password.changed - User password updated
api_key.created - New service API key generated
api_key.deleted - API key revoked
domain.set - Custom domain configured
domain.verified - Custom domain DNS verified
domain.deleted - Custom domain removed
branding.updated - Logo or primary color changed

SIEM Integration

siem_config.created - SIEM configuration created
siem_config.updated - SIEM settings updated
siem_config.deleted - SIEM integration removed

Webhook Security

Signature Verification

Each webhook request includes an X-Webhook-Signature header. This is an HMAC-SHA256 hex digest of the payload, signed using your webhook’s secret key.

const crypto = require('crypto');

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

Retries

If your server returns a non-2xx status code, AuthOS will retry the delivery up to 5 times with exponential backoff:

Immediate retry
After 1 minute
After 5 minutes
After 30 minutes
After 2 hours