Subscribing To Prehooks

Overview

Frontegg offers you 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 on a deny 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.

Step-By-Step Setup Guide

Follow the steps below to subscribe to prehook events.

STEP 1: Select Prehook Event

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

📘

For instance, go to the development environment at Environments ➜ Development ➜ Hooks ➜ Prehooks.


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 button

35843584

📘

Available Events For Prehooks

Read below to see a list of the available events for prehooks.

STEP 2: Enter Basic Details

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-secret and signs the prehook request using the secret. Therefore, for enhanced security, Frontegg recommends that you use the prehook secret.


For the fail methodology, select your preferred behavior:

  • Fail open: if the call is not successful or timed out, the operation will continue
  • Fail close: if the call is not successful or timed out, the operation will stop

35843584

STEP 3: Test Hook

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.

35843584

📘

When testing your setup, read more about working 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 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 you subscribe to a prehook, you may want to do some configuration. Read below to learn more about how to work with prehook events.

JWT Custom Claims

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.

Key

Value

sub

string

tenantId

string

roles

string[]

permissions

string[]

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:

Key

Value

tenantId

string

permissions

string[]

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:


14401440

📘

JWT custom claims survive so long as the JWT does. To change the JWT claims, you need to refresh the token.

Prehook Events List

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

Prehook Use Cases

Here are two common examples for how to use pre-hooks in your app:

Limiting sign ups to a specific number of users



Limiting user invitations



Did this page help you?