Frontegg offers you to setup prehooks so that you can control important aspects of user management.
As a user management platform, not surprisingly Frontegg controls critical user management flows, such as user signup, user invites, user update and more.
As an engineer, product developer, or executive, you may want the ability to dictate what happens in the user management flows.
Frontegg offers you prehooks to do exactly that. Subscribe to prehooks to receive a REST call every time the corresponding event is triggered.
Based on the response, your application can decide what to do. For instance, with prehooks you can configure your application to decide whether to continue a flow or stop it based on the logic in your application.
Here are some example use cases:
- Prevent signup if email is listed on a _denied _list.
- Prevent new member invitations based on a pre-set number or trial period.
- Add custom claims on JWTs used in the hosting application.
Read below to learn how to subscribe to and work with prehooks.
Follow the steps below to subscribe to prehook events.
In your Frontegg Portal, go to Environments ➜ [NAME OF ENVIRONMENT] ➜ Hooks ➜ Prehooks.
Prehook events are listed below
The page lists all your prehooks and has a button for adding a new prehook.
To select a prehook event:
- click on the add new hook button
- choose an event to trigger the prehook
- click the
Next, fill in the hook details.
The display name and description can be whatever you want.
For the URL, enter the URL at which you will receive the prehook data. The URL acts like an address that Frontegg can send a JSON message to when the assigned event happens.
For the secret key, enter a value that is confidential.
Frontegg generates a header called
x-webhook-secretand signs the prehook request using the secret. Therefore, for enhanced security, Frontegg recommends that you use the prehook secret.
In case the call for the hook endpoint failed (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
In order to create the hook, you are first required to verify that everything is setup correctly.
Click the run test button to verify, and then wait for the response. You should see the prehook data that you will receive and the response that Frontegg expects to receive from your application.
Before testing your setup, make sure you are familiar withworking with prehook events to get a better idea of how to configure the data in your response.
If the response is good, the prehook is ready!
Error Only Required If Continue is False
Note that the expected data includes error. The
errorfield is required in your response to Frontegg only if you set
continueto false. Also, you must set the error
statusbetween 400 and 499.
When you subscribe to a prehook, you may want to do some configuration. Read below to learn more about how to work with prehook events.
If you want to customize the data encoded by the JWT, subscribe to the prehook event for JWT Generation. It allows you to intercept the JWT and customize the JWT claims.
For subscriptions to the prehook for JWT Generation, 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 of the claims in the table below.
|metadata||Record <string, any>|
|type||userToken | userApiToken | tenantApiToken|
To override the default claims, include in your prehook response the data that you want to change.
Here are the claims you can include in your prehook response:
|customClaims||Record<string, unknown> | null|
If you do not customize the claims, the JWT will contain the default data.
When you subscribe to the JWT Generation prehook event, you need to test it.
The test page looks like the following:
JWT custom claims are available as long as JWT is. To change JWT claims, you need to refresh the token.
Here is a list of events available for using 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|
Here are two common examples of how to use pre-hooks in your app:
Updated about 1 month ago