Frontegg empowers you to control crucial aspects of user management by using prehooks.

With our comprehensive user management platform, Frontegg records and monitors vital user-related processes, including but not limited to user signup, user invites, various user actions in your app, and more.

Whether you're an engineer, product developer, or executive, prehooks help you to devise the desired responses after pivotal events happen in your app.

By subscribing to prehooks, your application receives a REST call whenever the associated event occurs. This call, coupled with the ensuing response, gives your application the capability to make informed decisions— for exampl, by leveraging prehooks, you can dynamically determine whether to proceed with a specific user management flow or terminate it— all based on the logic embedded within your application.

Prehook Use Cases

Prehook use cases may include:

  • Preventing user signup if a user's email is listed on a denied list.
  • Preventing new member invitations based on a pre-set number or trial period.
  • Adding custom claims to JWTs.

Check out the videos below to see how prehooks help limit sign-ups for a limited number of users and user invites:

🚧

Using Lambdas in Prehooks

We strongly advise to refrain from using Lambdas in Prehooks (unless your Lambdas are pre-warmed), Since cold Lambdas usually have a latency time that surpasses the 5 seconds prehook timeout. If your business case requires the use of Lambdas, please contact us to find the best solution.

Step-By-Step Prehook Setup

Subscribing to prehook events is done in 3 simple steps:

Step 1: Create a Prehook Event

Step 2: Enter Prehook Details

Step 3: Test Prehook

Create a Prehook Event

In your Frontegg Portal, go to Environments ➜ [NAME OF ENVIRONMENT] ➜ Hooks ➜ Prehooks.

  • Click on the Add new hook button.

📘

Prehook Events

A list of all supported prehook events can be viewed here.

  • Select a triggering event for your prehook.

Enter Prehook Details

Fill in the hook details.

  • Insert your preferred display name and description.
  • The URL should be address where you will receive the prehook data. The URL acts as an address where Frontegg sends a JSON message when the assigned event happens.
  • For the secret key, enter a value that is confidential (see note).

🚧

Secret Key

Frontegg generates a header called x-webhook-secret and signs the prehook request using the secret. Therefore, for enhanced security, Frontegg recommends that you use the prehook secret.

Setting Your Fail Methodology

In case the call for the hook's endpoint fails (response 500+ or request timeout, which is set to 5 seconds), you can set your fail methodology:

  • Fail open: if the call failed or timed out, the operation will continue.
  • Fail close: if the call failed or timed out, the operation will stop.

Test Prehook

To create the hook, you must first verify that everything was setup correctly.

Click the run test button to verify, then await the response. You should see the prehook data you will receive and the response Frontegg expects from your application.

📘

Prehook Testing

Before testing your setup, make sure you are familiar with working with prehook events.

If the response is valid, then your prehook is ready!

📘

Error Only Required If Continue is False

Note that the expected data includes error. The error field is required in your response to Frontegg only if you set continue to false. Also, you must set the error status between 400 and 499.

Working With Prehook Events

When subscribing to prehooks, you may want to adjust their configuration. Read on to learn how to work with prehook events.

JWT Custom Claims

If you want to customize the data encoded by the JWT, you need to subscribe to a prehook event for JWT Generation. This will allow you to intercept the JWT and customize the JWT claims.

For JWT Generation prehooks, Frontegg sends a new prehook event every time the hosting application requests a new JWT.

The prehook event sent to the hosting application contains whatever data Frontegg has stored for each claim in the table below.

KeyValue
substring
tenantIdstring
rolesstring[]
permissionsstring[]
metadataRecord <string, any>
typeuserToken | userApiToken | tenantApiToken

To override the default claims, include the data that you want to change in your prehook response.

You can include the following claims in your prehook response:

KeyValue
tenantIdstring
permissionsstring[]
customClaimsRecord<string, unknown> | null

📘

Customizing JWT Claims

The JWT will contain the default data unless you customize the JWT claims.

Test the JWT Generation prehook event like so:


📘

JWT Availability

JWT custom claims are available throughout the JWT's lifespan. To change JWT claims, you need to refresh the token.

Prehook Event List

The following list shows all available events that can be associated with prehooks:

EventEvent KeyWhen do we send it?
User signupUSER_SIGNUPLocal/Social/SSO sign ups
User inviteUSER_INVITEOn every user invite
User updateUSER_UPDATEOn every user update
User deleteUSER_DELETEWhen user is removed from tenant/completely deleted
JWT GenerationJWT_GENERATIONOn every JWT generation
Social login exchangeSOCIAL_LOGIN_AUTHOn each social login token exchange
Open ID connect authenticationOIDC_AUTHOn each OIDC authentication exchange
SAML authenticationSAML_AUTHOn each SAML authentication exchange