Documentation Index
Fetch the complete documentation index at: https://docs.mgpass.net/llms.txt
Use this file to discover all available pages before exploring further.
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
| Event | Description |
|---|
user.login.success | User signed in successfully |
user.login.failed | Authentication attempt failed |
User Lifecycle Events
| Event | Description |
|---|
user.register | New user account created |
user.suspended | User account suspended by admin |
user.unsuspended | User account unsuspended by admin |
user.deleted | User account deleted (soft delete) |
Session Events
| Event | Description |
|---|
session.created | New session established |
session.revoked | Session manually revoked |
Token Events
| Event | Description |
|---|
token.issued | Access token issued |
token.refreshed | Token refreshed via refresh token |
Role Events
| Event | Description |
|---|
role.assigned | Role assigned to a user |
role.removed | Role removed from a user |
Admin Events
| Event | Description |
|---|
user.impersonated | Admin 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_id": "usr_abc123",
"email": "kwame@example.com",
"method": "email_password",
"client_id": "app_xyz789"
}
{
"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;
}
