• Events (Webhook)
  • Endpoint
    • Parameters
  • Response
    • Status Codes (HTTP)
  • Actions
    • token_deleted
    • otp_requested
    • user_created
    • user_updated
    • password_reset
    • safety_reset

#Events (Webhook)

There should be a single endpoint for receiving events.

#Endpoint

Consider the following specs in designing your event handler endpoint:

#Parameters

#Response

#Status Codes (HTTP)

#Actions

#token_deleted

Your endpoint will receive the following payload when a token is deleted:

{
    "action": "token_deleted",
    "payload": {
        "token": "THE-DELETED-TOKEN"
    }
}

#otp_requested

Your endpoint will receive the following payload including the full original option object when you should send an OTP to a user via email or sms, etc.:

{
    "action": "otp_requested",
    "payload": {
        "option": {...},
        "ip": "xxx.xxx.xxx.xxx"
    }
}

#user_created

When using the built-in registration feature, your event will receive the following payload after the user successfully registers:

{
    "action": "user_created",
    "payload": {
        "user": {
            "username": "...",
            "email": "...",
            "phone": "...",
            "password": "...",
            "given_name": "...",
            "middle_name": "...",
            "family_name": "...",
            "nickname": "...",
            "website": "...",
            "gender": "...",
            "birthdate": "...",
            "address": "...",
            "location": "...",
            "zoneinfo": "...",
            "locale": "...",
            "custom_1": "...",
            "custom_2": "...",
            "custom_3": "...",
            "custom_4": "...",
            "custom_5": "...",
            "custom_6": "...",
            "custom_7": "...",
            "custom_8": "...",
            "custom_9": "..."
        },
        "ip": "xxx.xxx.xxx.xxx"
    }
}

Note that only the configured claims will be included in the payload.

#user_updated

When user updates their information using the built-in account (profile) page, your event will receive the following payload containing the updated claims of the user.

{
    "action": "user_updated",
    "payload": {
        "user": {
            "id": "1",
            "username": "...",
            "email": "...",
            "phone": "...",
            "given_name": "...",
            "middle_name": "...",
            "family_name": "...",
            "nickname": "...",
            "website": "...",
            "gender": "...",
            "birthdate": "...",
            "address": "...",
            "location": "...",
            "zoneinfo": "...",
            "locale": "...",
            "custom_1": "...",
            "custom_2": "...",
            "custom_3": "...",
            "custom_4": "...",
            "custom_5": "...",
            "custom_6": "...",
            "custom_7": "...",
            "custom_8": "...",
            "custom_9": "..."
        },
        "ip": "xxx.xxx.xxx.xxx"
    }
}

#password_reset

SSOfy does have a built-in password recovery tool for users which to be able to reset their password after verifying their identity using one of their available OTP verification options (Email, SMS, Call).

To utilize this, make sure that your OTP authentication response includes a temporary action token after the verification.

Your endpoint will receive the following payload when a password reset action is requested:

{
    "action": "password_reset",
    "payload": {
        "token": "TOKEN",
        "password": "YOUR_NEW_PASSWORD",
        "ip": "xxx.xxx.xxx.xxx"
    }
}

#safety_reset

It's possible for events to sometimes not reach your server. To ensure that your cache state is in sync with the most recent token status, a safety reset event will be initiated that may invalidate all cache states.

{
    "action": "safety_reset"
}