API prehook setup
Subscribing to prehook events is done in 3 simple steps:
Step 1: Create a prehook event
Open the Frontegg portal, then navigate to [ENVIRONMENT] ➜ Configurations ➜ Prehooks.
- Click the Create Prehook button.
Step 2: Enter prehook details
The next step would be to set your prehook information, and choose your prehook type. The Code type will indicate if the prehook is either an API or a custom prehook.
- Select a triggering event for your prehook.
- Insert your preferred display name and description.
- The URL should be the 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. For enhanced security, Frontegg recommends that you use the prehook secret.
To verify the hook's signature using the x-webhook-secret header, you should use a method from your backend library. For Node.js, you could use the following function:
jwt.verify(<x-webhook-secret-value>, <the secret in the dashboard on hook settings>)Step 3: Test your prehook
To finalize your hook creation, test your prehook to verify everything was setup correctly.
Click the run test button and then await the response— You should see the prehook data received and the response Frontegg expects from your application. If the response is valid, your prehook is ready to go, and you can enable it.
Error field
Error field
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
You may want to adjust the configuration of prehooks when subscribing. 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.
Customizing JWT claims
Customizing JWT claims
The JWT will contain the default data unless you customize the JWT claims and add your custom claims using the JWT prehook
For JWT Generation prehook, 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 |
To add to 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, note that tenantId and permissions cannot be overriden:
| Key | Value |
|---|---|
| tenantId | string |
| permissions | string [] |
| customClaims | Record <string, unknown> |
After customizing your JWT claims, you can test your hook:
Single prehook view
After testing and creating your prehook, you can view and adjust its settings. Each prehook has a Logs tab where you can see the triggered events associated with that prehook. Note that you can't change the Trigger event for custom prehooks after the connection is initiated.
