Prehooks
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 min 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
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 setcontinue
to false. Also, you must set the errorstatus
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.
Key | Value |
---|---|
sub | string |
tenantId | string |
roles | string[] |
permissions | string[] |
metadata | Record <string, any> |
type | userToken | 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:
Key | Value |
---|---|
tenantId | string |
permissions | string[] |
customClaims | Record<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:
Event | Event Key | When do we send it? |
---|---|---|
User signup | USER_SIGNUP | Local/Social/SSO sign ups |
User invite | USER_INVITE | On every user invite |
User update | USER_UPDATE | On every user update |
User delete | USER_DELETE | When user is removed from tenant/completely deleted |
JWT Generation | JWT_GENERATION | On every JWT generation |
Social login exchange | SOCIAL_LOGIN_AUTH | On each social login token exchange |
Open ID connect authentication | OIDC_AUTH | On each OIDC authentication exchange |
SAML authentication | SAML_AUTH | On each SAML authentication exchange |
Updated 3 months ago