Skip to main content

​
Overview

mgPass emits webhook events for identity lifecycle actions. These complement the rewards webhooks and use the same delivery and signature verification mechanism.

​
Identity Events

​
Authentication Events

EventDescription
user.login.successUser signed in successfully
user.login.failedAuthentication attempt failed

​
User Lifecycle Events

EventDescription
user.registerNew user account created
user.suspendedUser account suspended by admin
user.unsuspendedUser account unsuspended by admin
user.deletedUser account deleted (soft delete)

​
Session Events

EventDescription
session.createdNew session established
session.revokedSession manually revoked

​
Token Events

EventDescription
token.issuedAccess token issued
token.refreshedToken refreshed via refresh token

​
Role Events

EventDescription
role.assignedRole assigned to a user
role.removedRole removed from a user

​
Admin Events

EventDescription
user.impersonatedAdmin impersonated a user

​
Event Payload

All identity webhook events follow the same envelope format: 
{
  "id": "evt_abc123",
  "type": "user.login.success",
  "created_at": 1711900000,
  "data": {
    "user_id": "usr_abc123",
    "email": "kwame@example.com",
    "ip_address": "41.215.x.x",
    "user_agent": "Mozilla/5.0...",
    "method": "password"
  }
}

​
Event-Specific Data

user.login.success: 
{
  "user_id": "usr_abc123",
  "method": "password",
  "client_id": "app_xyz789",
  "ip_address": "41.215.x.x"
}
user.register: 
{
  "user_id": "usr_abc123",
  "email": "kwame@example.com",
  "method": "email_password",
  "client_id": "app_xyz789"
}
role.assigned: 
{
  "user_id": "usr_abc123",
  "role_id": "role_subscriber",
  "role_name": "subscriber",
  "assigned_by": "usr_admin456"
}

​
Signature Verification

Identity webhooks use the same HMAC-SHA256 signature verification as rewards webhooks. The signature is sent in the X-Webhook-Signature header. 
import { createHmac } from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signature === expected;
}
See the rewards webhooks guide for full details on webhook configuration and retry behavior.