Webhook Events Reference

Complete reference of all webhook event types supported by AuthOS.

Event Categories

Category	Events	Description
User Lifecycle	4	Signup, login, logout events
User MFA	4	MFA enable, disable, verification
User Management	4	Invites, joins, removals, role changes
Service Management	4	Service CRUD and OAuth updates
Organization	3	Organization and SMTP updates
Plan Management	3	Plan CRUD operations
Subscription	3	Subscription lifecycle
Invitation	4	Invitation lifecycle
Security	3	Security-related admin actions
API Keys	2	API key management
Domain & Branding	4	Custom domain and branding

Webhook Payload Format

All webhook payloads follow this structure:

{
  "event": "event.type.name",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    // Event-specific data
  }
}

Common Fields

Field	Type	Description
`event`	`string`	Event type identifier
`timestamp`	`string`	ISO 8601 timestamp
`organization_id`	`string`	Organization UUID
`data`	`object`	Event-specific payload

User Lifecycle Events

user.signup.success

Fired when a new user successfully registers.

{
  "event": "user.signup.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "service_id": "service-uuid",
    "auth_method": "password | oauth:github | oauth:google | oauth:microsoft"
  }
}

user.login.success

Fired when a user successfully authenticates.

{
  "event": "user.login.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "service_id": "service-uuid",
    "auth_method": "password | oauth:github | mfa | magic_link | passkey",
    "ip_address": "192.168.1.1",
    "user_agent": "Mozilla/5.0..."
  }
}

user.login.failed

Fired when a login attempt fails.

{
  "event": "user.login.failed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "email": "user@example.com",
    "service_id": "service-uuid",
    "reason": "invalid_credentials | account_locked | mfa_failed | email_not_verified",
    "ip_address": "192.168.1.1"
  }
}

user.logout

Fired when a user logs out.

{
  "event": "user.logout",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "session_id": "session-uuid"
  }
}

User MFA Events

user.mfa.enabled

Fired when a user enables MFA on their account.

{
  "event": "user.mfa.enabled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "mfa_type": "totp"
  }
}

user.mfa.disabled

Fired when a user disables MFA.

{
  "event": "user.mfa.disabled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com"
  }
}

user.mfa.verify.success

Fired when MFA verification succeeds during login.

{
  "event": "user.mfa.verify.success",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "method": "totp | backup_code"
  }
}

user.mfa.verify.failed

Fired when MFA verification fails.

{
  "event": "user.mfa.verify.failed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "attempt_count": 3,
    "ip_address": "192.168.1.1"
  }
}

User Management Events

user.invited

Fired when a user is invited to join the organization.

{
  "event": "user.invited",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "invitation_id": "invitation-uuid",
    "email": "invitee@example.com",
    "role": "member | admin",
    "invited_by": "admin-user-uuid"
  }
}

user.joined

Fired when a user joins the organization (accepts invitation or SCIM provisioned).

{
  "event": "user.joined",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "role": "member",
    "method": "invitation | scim"
  }
}

user.removed

Fired when a user is removed from the organization.

{
  "event": "user.removed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "removed_by": "admin-user-uuid"
  }
}

user.role_updated

Fired when a user’s role is changed.

{
  "event": "user.role_updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "old_role": "member",
    "new_role": "admin",
    "updated_by": "owner-user-uuid"
  }
}

Service Management Events

service.created

Fired when a new service is created.

{
  "event": "service.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "service_id": "service-uuid",
    "slug": "my-app",
    "name": "My Application",
    "created_by": "admin-user-uuid"
  }
}

service.updated

Fired when service configuration is updated.

{
  "event": "service.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "service_id": "service-uuid",
    "slug": "my-app",
    "updated_fields": ["name", "redirect_uris"],
    "updated_by": "admin-user-uuid"
  }
}

service.deleted

Fired when a service is deleted.

{
  "event": "service.deleted",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "service_id": "service-uuid",
    "slug": "my-app",
    "deleted_by": "admin-user-uuid"
  }
}

service.oauth_credentials.updated

Fired when a service’s OAuth credentials are updated.

{
  "event": "service.oauth_credentials.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "service_id": "service-uuid",
    "provider": "github | google | microsoft",
    "updated_by": "admin-user-uuid"
  }
}

Organization Events

organization.updated

Fired when organization settings are updated.

{
  "event": "organization.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "updated_fields": ["name"],
    "updated_by": "admin-user-uuid"
  }
}

organization.smtp.configured

Fired when SMTP settings are configured or updated.

{
  "event": "organization.smtp.configured",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "from_email": "noreply@example.com",
    "configured_by": "admin-user-uuid"
  }
}

organization.smtp.removed

Fired when SMTP settings are removed.

{
  "event": "organization.smtp.removed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "removed_by": "admin-user-uuid"
  }
}

Plan Management Events

plan.created

Fired when a new subscription plan is created.

{
  "event": "plan.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "plan_id": "plan-uuid",
    "name": "Pro Plan",
    "service_id": "service-uuid",
    "created_by": "admin-user-uuid"
  }
}

plan.updated

Fired when a plan is updated.

{
  "event": "plan.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "plan_id": "plan-uuid",
    "updated_fields": ["price", "features"],
    "updated_by": "admin-user-uuid"
  }
}

plan.deleted

Fired when a plan is deleted.

{
  "event": "plan.deleted",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "plan_id": "plan-uuid",
    "name": "Pro Plan",
    "deleted_by": "admin-user-uuid"
  }
}

Subscription Events

subscription.created

Fired when a user subscribes to a plan.

{
  "event": "subscription.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "subscription_id": "sub-uuid",
    "user_id": "user-uuid",
    "plan_id": "plan-uuid",
    "plan_name": "Pro Plan"
  }
}

subscription.updated

Fired when a subscription is modified (plan change, renewal).

{
  "event": "subscription.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "subscription_id": "sub-uuid",
    "user_id": "user-uuid",
    "old_plan_id": "plan-uuid-old",
    "new_plan_id": "plan-uuid-new"
  }
}

subscription.canceled

Fired when a subscription is canceled.

{
  "event": "subscription.canceled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "subscription_id": "sub-uuid",
    "user_id": "user-uuid",
    "plan_id": "plan-uuid",
    "cancel_at_period_end": true
  }
}

Invitation Events

invitation.accepted

Fired when an invitation is accepted.

{
  "event": "invitation.accepted",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "invitation_id": "invitation-uuid",
    "user_id": "user-uuid",
    "email": "user@example.com",
    "role": "member"
  }
}

invitation.declined

Fired when an invitation is declined.

{
  "event": "invitation.declined",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "invitation_id": "invitation-uuid",
    "email": "user@example.com"
  }
}

invitation.expired

Fired when an invitation expires.

{
  "event": "invitation.expired",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "invitation_id": "invitation-uuid",
    "email": "user@example.com",
    "originally_invited_by": "admin-user-uuid"
  }
}

invitation.revoked

Fired when an invitation is revoked by an admin.

{
  "event": "invitation.revoked",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "invitation_id": "invitation-uuid",
    "email": "user@example.com",
    "revoked_by": "admin-user-uuid"
  }
}

Security Events

security.mfa.enabled

Fired when MFA is enabled (admin-level security event).

{
  "event": "security.mfa.enabled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com"
  }
}

security.mfa.disabled

Fired when MFA is disabled (admin-level security event).

{
  "event": "security.mfa.disabled",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "disabled_by": "admin-user-uuid | self"
  }
}

security.password.changed

Fired when a user changes their password.

{
  "event": "security.password.changed",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "user_id": "user-uuid",
    "email": "user@example.com",
    "ip_address": "192.168.1.1"
  }
}

API Key Events

api_key.created

Fired when an API key is created.

{
  "event": "api_key.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "api_key_id": "key-uuid",
    "name": "Production API Key",
    "prefix": "sk_live_abc1",
    "scopes": ["read:users", "write:users"],
    "created_by": "admin-user-uuid"
  }
}

api_key.deleted

Fired when an API key is deleted.

{
  "event": "api_key.deleted",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "api_key_id": "key-uuid",
    "name": "Production API Key",
    "deleted_by": "admin-user-uuid"
  }
}

Domain & Branding Events

domain.set

Fired when a custom domain is configured.

{
  "event": "domain.set",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "domain": "auth.example.com",
    "set_by": "admin-user-uuid"
  }
}

domain.verified

Fired when a custom domain passes DNS verification.

{
  "event": "domain.verified",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "domain": "auth.example.com"
  }
}

domain.deleted

Fired when a custom domain is removed.

{
  "event": "domain.deleted",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "domain": "auth.example.com",
    "deleted_by": "admin-user-uuid"
  }
}

branding.updated

Fired when branding settings are updated.

{
  "event": "branding.updated",
  "timestamp": "2025-01-15T10:30:00Z",
  "organization_id": "org-uuid",
  "data": {
    "updated_fields": ["logo_url", "primary_color"],
    "updated_by": "admin-user-uuid"
  }
}

Webhook Delivery

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

Maximum of 5 delivery attempts per event.

Signature Verification

Webhooks include an HMAC-SHA256 signature for verification:

X-Webhook-Signature: sha256=abc123...
X-Webhook-Timestamp: 1705315800

Verify the signature in your handler:

const crypto = require('crypto');

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