Skip to main content

SlashID Synchronous Hooks

SlashID synchronous hooks are points during our internal flows where you are able to gain visibility and potentially affect the outcomes.

Synchronous Hook Content and Response​

Synchronous hooks can be used as triggers for webhooks. The exact trigger content in the webhook request will depend on the type of hook. Your application may include a response body, which may be used to affect the hooked flow, again depending on the type of hook. See below for details on each hook's content and response.

Note that if you have multiple webhooks for a single trigger, there is no guarantee on the order in which we call them, and they may be called simultaneously. You should consider this when crafting responses.

Synchronous Hook Points​

Currently, SlashID supports the following synchronous hooks:

Token Minted​

The token_minted hook point occurs during user authentication, after the user has successfully authenticated, and before we issue the signed user token. It can be used to enrich the token with additional claims before it is signed and issued to the user.

Note that this hook does not apply to tokens issued by the token minting API.

Token Minted Hook Content​

The content of this hook is a subset of the claims that will be present in the issued token, along with metadata about the original request.

The hook content will contain the following fields from the token:

  • aud: the JWT audience claim, equal to your organization ID
  • sub: the JWT subject claim, equal to the person ID of the user who just authenticated
  • iss: the JWT issuer claim
  • prev_token_id: the ID of the user's previous token, if any
  • region: the region where the user's data resides
  • first_token: whether this is the first token ever issued for this user (first authentication)
  • authentications: a list of AuthenticationDetails objects describing how the user has authenticated (see below)
  • groups_claim_name: the name of the claim that will contain the user's groups in the final token
  • groups: the groups the user belongs to, if any
  • custom_claims: a freeform map of custom claims that will be included in the token, if any
  • oidc_tokens: a list of OIDCTokens objects containing data about OIDC authentications this user has performed
  • request_metadata: a RequestMetadata object containing data about the request that caused the token to be minted.

The AuthenticationDetails object contains the following fields:

  • timestamp: the time when the authentication occurred
  • method: the authentication method, for example email_link or webauthn
  • handle: a PersonHandle object describing the handle used for this authentication.

The PersonHandle object contains the following fields:

  • type: the type of handle, either email_address or phone_number
  • value: the value of the handle itself

The OIDCTokens object contains the following fields:

  • provider: the OIDC provider the user authenticated with
  • client_id: the client ID used in the OIDC authentication
  • oidc_groups: the groups for the user in the OIDC provider

The RequestMetadata object contains the following fields:

  • origin: the value of the Origin header from the request, if present
  • user_agent: the value of the User-Agent header from the request, if present
  • client_ip_address: the IP address from which the request originated, if present

Note that in some jurisdictions the handle value and client IP may be regarded as PII, and you should consider this when implementing your webhooks.

Token Minted Hook Response​

info

Your application must return a 2XX status code in the response for the webhook call to be treated as successful. Note that 1XX information codes and 3XX redirect codes are not accepted, and are not regarded as successful.

The token minted hook accepts responses containing sets of custom claims as key-value pairs. For example, if the webhook response body was

{
  "division": "R&D",
  "name": "Alex Singh"
}

then the issued token would have claims like

{
  "aud": "<your organization ID>",
  "sub": "<authenticated person's ID>",
  "iss": "https://api.slashid.com",
  ...
  "groups": ["admin", "it"],
  "division": "R&D",
  "name": "Alex Singh"
}

Some claim names are reserved and cannot be added as custom claims - see a full list in our API documentation.

If multiple webhooks are called for a single trigger, and they all return response bodies, all custom claims present in the responses will be added to the token. If multiple responses contain the same custom claims, the last one to be parsed will overwrite previous values. As there is no guarantee of order when calling webhooks or parsing responses, we recommend that webhooks return disjoint sets of claims.

Identify User​

The identify_user hook point occurs during the initial user identification process, before any authentication challenges are issued. It can be used to modify the identification request, including changing the organization ID or authentication factor.

Identify User Hook Content​

The content of this hook includes:

  • id_request: The identification request object containing:
    • factor: The authentication factor details
      • method: The authentication method being used.
      • options: Method-specific options
    • handle: The user handle being used for identification
      • type: The handle type (email_address or phone_number)
      • value: The actual handle value
  • previous_token: The user's previous token, if any

The following is an example of the decoded hook request data:

{
    "aud": "00000000-0000-0000-0000-000000000000",
    "exp": 1730990394,
    "iat": 1730990094,
    "iss": "https://api.slashid.com",
    "jti": "11111111-1111-1111-1111-111111111111",
    "sub": "22222222-2222-2222-2222-222222222222",
    "target_url": "https://your.domain.com/some-hook",
    "trigger_content": {
            "id_request": {
                    "factor": {
                            "method": "email_link",
                            "options": null
                        },
                    "handle": {
                            "type": "email_address",
                            "value": "giovanni+lsjbns@slashid.dev"
                        },
                    "identifier": {
                            "type": "email_address",
                            "value": "giovanni+lsjbns@slashid.dev"
                        }
                },
            "previous_token": null
        },
    "trigger_name": "identify_user",
    "trigger_type": "sync_hook",
    "webhook_id": "33333333-3333-3333-3333-333333333333"
}

Identify User Hook Response​

The identify user hook accepts responses that can modify the identification flow. All values are optional. The response may include:

  • org_id: A new organization ID to use for the authentication flow
  • factor: Modified authentication factor details
    • method: A new authentication method to use. Factor methods are defined in the SDK reference
    • options: New method-specific options.

Values allowed for options:

For example, to change the organization and authentication method:

{
  "org_id": "51b7f2da-2b9a-40fc-909d-f42e9229308e",
  "factor": {
    "method": "sms_link",
    "options": {
      "redirect_target": "https://redirect-example.com"
    }
  }
}

Note that when changing the organization ID, the new organization must share the same root organization as the original request. Attempting to switch to an organization under a different root will result in an error.