Custom Hooks

There will be times you want to modify some flows or you want to apply some logic for some actions. PlusAuth provides hooks for you to be able to modify the flow and use your own logic.

Hooks are executed on a secure sandbox, and they will throw timeout error after 10 seconds, causing to fail the hook.

Create Hook

Go to Dashboard > Hooks and click to + button from bottom right of the screen to create a hook. You will be redirected a page where you will enter the name, description, type of the hook and the content to execute. After you fill required fields you will see a save button appeared on the bottom right of the screen. Clicking that button will save your hook.

After saving the hook you can add any npm modules that supports Node.js v14. Also your content should be able to run on Node.js 14.

Your hook context must have a function named handle which receives two parameters. First parameter is a data parameter which contains hook context. See Hook Context for detailed information. The second parameter is a callback function which you should call with final hook context as second parameter when your job is done or with an error as first parameter you want to throw. Have a look at below for more concrete example:

function handle(data, callback){
  if(someCondition){
    // hook executes successfully
    callback(null, data)
  }else{
    // hook fails with an error
    callback(new Error('condition failed'))
  }
}

Alternatively, you can use promise-like interface like this:

function handle(data){
  if(someCondition){
    // hook executes successfully
    return data
  }else{
    // hook fails with an error
    throw new Error('condition failed')
  }
}

Change Order of Hooks

You can create hooks with the same type and their execution order could be somehow important for you. In those cases all you need to do is change the order for those hooks. Go to Dashboard > Hooks. You will see a table with sections of hook types. You can drag and drop the hooks in the same type change their order.

Adding Modules

After you create your hook, you can add modules for that hook by clicking Add npm package button from the left of the content editor. You will see a search bar on the screen where you can write down your npm package name that will be searched over npm registry. From the list you can click to the plus icon to add that module and you will see console output for that package installation. If the module already exists and its version is outdated you will see an update icon instead of plus icon to update the installed package.

Your modules must be compatible with NodeJS v14

Testing Hook

You can test your hook with the Run button located on the right sidebar of content editor. It will use a test context which contains will be in the same structure as the real usage but it's content will be generated randomly.

After you click the Run button you will see console output and resulting context from the console window.

Hook Context

key	description
client	Client object that initiated the flow.
user	PlusAuth user object.
context.request.query	Query parameters for initiated request
context.request.body	Request body for initiated request
context.request.headers	Request headers for initiated request
context.request.userAgent	UserAgent for initiated request
context.request.ip	IP of incoming request
context.response.body	Response body object
context.response.headers	Headers which will be sent
context.authParams	Authorization related params.
context.accessToken	Generated access token.
context.idToken	Generated id token.

Some of the properties listed above could be undefined in some hook types or flows. Make sure to handle cases for them being undefined in your hook code.

Hook Types

Hooks registered with this type will execute before users sign in process. This hook will be executed if the user exists even if password verification failed.

Hooks registered with this type will be executed when all the checks have passed for sign in process and user is successfully logged in to the system.

PRE REGISTER

Hooks registered with this type will be executed just before saving the user to the database or to the external connection. If you modify the user object in this hook, modified version will be saved into the database.

POST REGISTER

Hooks registered with this type will be executed when user is successfully stored into database or external connection.

Hooks