Events and Hooks

Event are generated and delivered to your hooks. You will be notified when important events such as new user signup happen.

Events are divided into two kinds, Blocking and Non-blocking.

Each event can have multiple hooks. The delivery order of non-blocking events is unspecified. Blocking events are delivered in the order as in the configuration.

Event Body

Events have the following shape as the body:

{
  "id": "0E1E9537-DF4F-4AF6-8B48-3DB4574D4F24",
  "seq": 435,
  "type": "user.pre_create",
  "payload": { /* ... */ },
  "context": {
    "app_id": "project-1"
    "client_id": "bfb2e0e0e7f3cfa2"
    "timestamp": 1670570552,
    "user_id": "f333b70b-4436-4efb-a40b-d9ed7a74d319",
    "preferred_languages": ["en-US", "zh-HK"],
    "language": "en-US",
    "triggered_by": "user"
    "oauth": {
      "state": "eyJ0b2tlbiI6IlgxS1RRTUM1TkRRUzQzOFAifQ"
    },
    "ip_address": "178.238.11.6",
    "geo_location_code": "GB",
    "user_agent": " Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.79 Safari/537.36",

  }
}

• id: The ID of the event.

• seq: A monotonically increasing signed 64-bit integer.

• type: The type of the event.

• payload: The payload of the event, varies with type. See Blocking Events and Non-blocking Events for the detailed payload for each event.

• context: The context of the event.

Event Context

The body of the context provides the details about the client and authentication signal collected:

• app_id: The ID of the Authgear project.

• client_id: The client ID of the application, if present.

• timestamp: signed 64-bit UNIX timestamp of when this event is generated. Retried deliveries do not affect this field.

• user_id: The ID of the user associated with the event. It may be absent. For example, the user has not authenticated yet.

• ip_address: The IP address of the HTTP request, if present.

• user_agent: The User-Agent HTTP request header, if present.

• triggered_by: The origin of the event, possible values are:

  • user: The event originates from a end-user facing UI.

  • admin_api: The event originates from the Admin API.

  • system: The event originates from a background job.

  • portal: The event originates from the management portal that does not use the Admin API, for example, "Collaborator invitation accepted", "Domain created".

• preferred_languages: User preferred languages which are inferred from the request. It is the value of ui_locales query parameter if it is provided, or the value of the Accept-Language header. It is an empty array when the event is not generated by the end user.

• language: The locale which is derived based on user's preferred languages and app's languages config. The fallback value is the fallback language of the app.

• geo_location_code: The (ISO 3166-1 alpha-2 code)[https://www.iban.com/country-codes] of the location derived from the ip address. null if the location cannot be determined by the ip address, for example, it is an internal ip address.

• oauth: Data related to OAuth. The field does not exist if the event is not from an OAuth flow (Such as SAML login).

  • state: state of the authorization request.

  • x_state: x_state of the authorization request.

Blocking Events

Blocking events are triggered before the operation is performed, such as before user creation. This allow you to abort or alter the operations programmatically.

Learn more in:

Blocking Events

Non-blocking Events

Non-blocking events are triggered after the operation is performed. They are delivered to your hooks asynchronously after the operation is performed.

Learn more in:

Non-blocking Events

Event Trigger Points in Signup/Login Flows

This section outlines when each event is triggered within the default signup and login flows, helping you understand where your hooks can interact with Authgear.

Note that the event timing may be changed in a customized authentication flow.

Legends:

• Blue: Blocking events

• Green: Non-blocking events

Default Signup flow

Default Login Flow