Events (Webhook)

There should be a single endpoint for receiving events.

Consider the following specs in designing your event handler endpoint:

URLanything
MethodPOST
HeadersContent-Type, Signature
FormatJSON
AttributeTypeRequired
actionstringYes
payloadarrayNo
CodeDescription
200Success
400Signature/Input validation Failed

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

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

📌 Info

It is optional to handle this event.

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"
    }
}

📌 Info

It is optional to handle this event.

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.

📌 Info

It is optional to handle this event.

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"
    }
}

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).

📌 Info

It is optional to handle this event.

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"
    }
}

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"
}
ssofy Knowledge Base
At our core, we believe that staying up-to-date with the latest trends and advancements in Authentication and related areas is essential. That's why we take great pride in keeping you informed with the latest insights, updates, and news in this rapidly evolving landscape.


Do you need support?
SSOfy is by Cubelet Ltd.
Copyright © 2024 Cubelet Ltd. All rights reserved.