Webhook
Webhook is a provision in cidaas that allows executing business specific requirements when specific events occur during the registration or login.
cidaas provides a Webhook URL (location / client's Webhook receiver) and key to be configured by the Administrator user.
Find the below pre-defined events list cidaas provides:
Webhook | Description |
---|---|
ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY |
A user has been registered through a login UI. |
ACCOUNT_CREATED_WITH_SOCIAL_IDENTITY |
A user has been registered by using a social identity provider e.g. Google Plus, Facebook. |
ACCOUNT_DELETED |
A user account has been deleted. |
ACCOUNT_MODIFIED |
User account details have been modified by an user or an admin. |
ACCOUNT_EMAIL_VERIFIED |
An email address of a user has been verified. |
ACCOUNT_MOBILE_NO_VERIFIED |
A mobile number of a user has been verified. |
ACCOUNT_EMAIL_UNVERIFIED |
An email address of a user has been unverified. |
ACCOUNT_MOBILE_NO_UNVERIFIED |
A mobile number of a user has been unverified. |
ACCOUNT_ACTIVATED |
A user account has been activated. |
ACCOUNT_DEACTIVATED |
A user account has been deactivated. |
ACCOUNT_SOCIALIDENTITY_ADDED |
A social identity has been added to a user account. |
ACCOUNT_SOCIALIDENTITY_REMOVED |
A social identity has been unlinked/removed from a user account. |
ACCOUNT_CIDAASIDENTITY_ADDED |
A cidaas account has been linked to another cidaas account. E.g. a new user has been registered with an already existing email address. |
ACCOUNT_CIDAASIDENTITY_REMOVED |
A cidaas account has been unlinked from another cidaas account. |
PASSWORD_CHANGED |
The password of a user has been changed. |
EMAIL_CHANGED |
The email address of a user has been changed. |
PASSWORD_RESET_INITIATE |
The reset of a password of a user has been initiated. |
PASSWORD_RESET |
The password of a user has been resetted. |
COMBINED |
Combine/link the user accounts if a user has two account with different email addresses. |
LOGOUT |
A user has been logged out. |
TOKEN_CHECKED |
An access token has been checked successfully as valid. |
TOKEN_RENEWED |
An access token has been renewed using a refresh token. |
CODE_OBTAINED |
An authorization request with the responsetype code has been received. |
ACCESS_TOKEN_OBTAINED |
An authorization request with the responsetype token has been received. |
LOGIN_WITH_CIDAAS |
A user has been logged in through cidaas login ui. |
LOGIN_WITH_SOCIAL |
A user has been logged using a social idendity provider. (facebook, google...) |
APP_CREATED |
A new cidaas app has been created. |
APP_MODIFIED |
A cidaas app has been updated. |
APP_DELETED |
A cidaas app has been deleted. |
GROUP_UPDATED |
A cidaas group has been updated. |
LOGIN_FAILURE |
A user has tried to login and the login was not successful. E.g. A user has tried to login with wrong credentials (invalid username/password). |
ROLE_CREATED |
A new user role has been created. |
ROLE_DELETED |
A user role has been removed. |
SOCIAL_PROVIDER_ENABLED |
A social provider has been enabled for an app. |
SOCIAL_PROVIDER_DISABLED |
A social provider has been disabled for an app. |
GROUP_FIRST_ADMIN_ADDED |
The "Make First User Admin" switch is enabled in a cidaas group and a new user has been added to this particular cidaas group. |
GROUP_ADMIN_ADDED |
A user has been added to a cidaas group with the GROUP_ADMIN role. |
GROUP_NEW_USER_ADDED |
A new user has been added to a cidaas group. |
INVITE_USER |
An invitation flow has been started and a new user has been invited. |
INVITE_ACCEPTED |
A user has been registered through a invitation. |
GROUP_USER_ROLE_UPDATED |
The roles of a user in a cidaas group has been updated. |
GROUP_USER_REMOVED |
A user has been removed from a cidaas group. |
DEVICE_CREATED |
An access control device has been added to cidaas. |
DEVICE_UPDATED |
An access control device has been updated. |
DEVICE_DELETED |
An access control device has been deleted from cidaas. |
TENANT_CREATED |
A tenant in cidaas has been created. |
GROUP_CREATED |
A custom user group has been created. |
GROUP_DELETED |
A custom user group has been deleted. |
SMS_SENT |
A SMS has been sent from cidaas. E.g. A user has ordered a MFA for mobile verification and the verification code SMS has been sent. |
EMAIL_SENT |
An email has been sent from cidaas. E.g. A verification mail has been sent to a user. |
IVR_TRIGGERED |
A verification code has been sent via voice call. |
PUSH_SENT |
A verification code has been sent via push notificiation to the cidaas authenticator mobile app. |
SCOPE_CREATED |
A new scope has been created. |
SCOPE_UPDATED |
A scope has been updated. |
SCOPE_DELETED |
A scope has been deleted. |
REGISTRATION_FIELD_CREATED |
A new user registration field has been created. |
REGISTRATION_FIELD_UPDATED |
A user registration field has been updated. |
REGISTRATION_FIELD_DELETED |
A user registration field has been deleted. |
GROUP_TYPE_CREATED |
A new group type has been created. |
GROUP_TYPE_UPDATED |
A group type has been updated. |
GROUP_TYPE_DELETED |
A group type has been deleted. |
HOSTED_PAGE_CREATED |
A new hosted page has been created. |
HOSTED_PAGE_UPDATED |
A hosted page has been updated. |
HOSTED_PAGE_DELETED |
A hosted page has been delezed. |
TEMPLATE_UPDATED |
A template has been updated. |
CUSTOM_TEMPLATE_CREATED |
A new custom template has been created. |
CUSTOM_TEMPLATE_UPDATED |
A custom template has been updated. |
CUSTOM_TEMPLATE_DELETED |
A custom template has been deleted. |
WEBHOOK_CREATED |
A new webhook has been created. |
WEBHOOK_UPDATED |
A webhook has been updated. |
WEBHOOK_DELETED |
A webhook has been deleted. |
CAPTCHA_CREATED |
A new captcha has been created. |
CAPTCHA_UPDATED |
A captcha has been updated. |
PROFILE_IMAGE_UPDATED |
A user profile image has been updated. |
PROFILE_IMAGE_REMOVED |
A user profile image has been removed. |
MFA_REQUIRED |
A login with a requiredMFA Required in cidaas |
USER_REGION_STARTED |
A new user region process has started. |
USER_REGION_IN_PROGRESS |
The user region is in progress. |
USER_REGION_ENDED |
A user region process has ended. |
PHYSICAL_VERIFICATION_CONFIG |
A user has configured a physical verification setup. E.g. email, SMS, face id, ... |
PHYSICAL_VERIFICATION_REMOVED |
A user has removed a physical verification setup. |
PHYSICAL_VERIFICATION |
A user has used a physical verification. |
CUSTOMER_CREATED |
A new customer has been created. |
CUSTOMER_UPDATED |
A customer has been updated. |
CUSTOMER_DELETED |
A customer has been deleted. |
PRODUCT_BUNDLE_CREATED |
A new product bundle has been created. |
PRODUCT_BUNDLE_UPDATED |
An existing product bundle has been updated. |
PRODUCT_BUNDLE_DELETED |
A product bundle has been deleted. |
SERVICE_PACKAGE_PURCHASED |
A service package has been purchased. |
CONTRACT_CREATED |
A new contract has been created. |
CONTRACT_UPDATED |
An existing contract bundle has been updated. |
CONTRACT_DELETED |
A contract has been deleted. |
TENANT_CONFIG_CREATED |
A new tenant config has been created. |
TENANT_CONFIG_UPDATED |
An existing tenant config has been updated. |
TENANT_CONFIG_DELETED |
A tenant config has been deleted. |
CREDITS_ADDED_TO_CONTRACT |
Credits have been purchased and added to an existing contract. |
CREDITS_ADDED_TO_TENANT |
Credits have been purchased and added to an existing tenant. |
DOOR_OPENED |
An access control door has been opened successfully through the mobile application or by using the door api. |
GEOFENCE_ENTER |
An in the access control defined geofence has been entered. |
GEOFENCE_EXIT |
An in the access control defined geofence has been exited. |
CUSTOM_CODE_VERIFICATION_TRIGGERED |
A custom code verification flow has been triggered. |
Webhook modification
Create Webhook
1. Click “Create Webhook” button.
2. Select the Webhook events from the drop down.
3. Enter the Webhook URL.
4. Administrator can secured your url by using the following any one methods:
- API-Key Enter the Webhook API-Key, as in the below screen
- TOTP Key Enter the Webhook TOTP-Key, as in the below screen
- cidaas Oauth2 Enter the Webhook cidaas Oauth2, as in the below screen
5. Click “Save” button, a message window popup “Webhook Saved Successfully” 6. Click “OK” button, the webbook grid table get displayed as in the below screen
Edit Webhook Template
1. From the created Webhooks, click on the icon Edit Template
2. Edit the appropriate changes
3. Click “Save” button.
Delete Webhook Template
1. From the created Webhooks, click on the delete icon.
2. A confirmation window popup to delete the Webhooks.
3. Click “YES” button to confirm the delete or click “NO” button to cancel the delete.
Client Webhook Receiver Implementation
The Client Webhook receiver needs to handle the following:
1. Receive the event and acknowledge the cidaas Webhook event.
2. Get Access Token.
3. Get User Info.
4. Handle the Event Types.
5. Receive the Event and acknowledge the cidaas Webhook: That is, parse the payload from the cidaas Webhook event and respond back with 200 ok, if not this will appear in the failed Webhooks report.
6. Get Access Token: Use your Non-Interactive Client application's client_id and client_secret to obtain the access_token from cidaas.
7. Let us see how by using sample node js application:
This is my sample node js application's folder structure
TokenResolver.js
var request = require('request');
var getAccessToken = (config, callback) => {
var options = {
uri: config.token_url,
form: {
grant_type: 'client_credentials',
client_id: config.client_id,
client_secret: config.client_secret
}
};
request.post(options, (error, response, body) => {
if (error) {
callback({
error: error
});
return;
}
if (body && typeof body == "string") {
try {
body = JSON.parse(body);
callback({
error: null,
data: body
});
return;
} catch (error) {
console.log("error while parsing");
}
}
callback({
error: "error while getting token info"
});
});
};
module.exports = {
getAccessToken: getAccessToken
};
1. Get User Info
UserinfoResolver.js
var request = require('request');
var getUserInfo = (config, userId, access_token, callback) => {
var options = {
uri: config.userinfo_url + "/" + userId,
headers: {
"access_token": access_token,
"content-type": 'application/json'
}
};
request.get(options, (error, response, body) => {
if (error) {
callback({
error: error
});
return;
}
if (body && typeof body == "string") {
try {
body = JSON.parse(body);
callback({
error: null,
data: body
});
return;
} catch (error) {
console.log("error while parsing");
}
}
callback({
error: "error while getting user info"
});
});
};
module.exports = {
getUserInfo: getUserInfo
};
2. Handle the Event Types
WebhookHandlerController.js
var HttpStatus = require('http-status-codes');
var request = require('request');
var async = require('async');
var tokenResolver = require.main.require("./Model/TokenResolver.js");
var userInfoResolver = require.main.require("./Model/UserInfoResolver.js");
var cidaasConfig = require.main.require("./Resources/conf/cidaas-service.json");
module.exports = function(app) {
/**
* Sample Body JSON
{
"eventtype":"ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY",
"userId":"09874dac-f3bc-422a-b169-786f2a079157",
"createTime":1472451637774,
"providerName":"Facebook",
"client_id":"5a5a0a92511f46a58e505d223e0eddb4"
}
*/
app.post("/receiver", function(req, res) {
var requestData = req.body;
async.parallel({
handlewebhook: function(callback) {
try {
tokenResolver.getAccessToken(cidaasConfig, (tokenResponse) => {
if (tokenResponse.error) {
callback(null, {
error: tokenResponse.error,
status: HttpStatus.INTERNAL_SERVER_ERROR
});
return;
}
userInfoResolver.getUserInfo(cidaasConfig, requestData.userId, tokenResponse.data.access_token, (userInfo) => {
if (userInfo.error) {
callback(null, {
error: userInfo.error,
status: HttpStatus.INTERNAL_SERVER_ERROR
});
return;
}
switch (requestData.eventtype) {
case "ACCOUNT_CREATED_WITH_CIDAAS_IDENTITY":
case "ACCOUNT_CREATED_WITH_SOCIAL_IDENTITY":
console.log("New user created in cidaas ");
console.log(userInfo);
callback(null, {
data: "New user created in cidaas ",
status: HttpStatus.OK
});
break;
case "LOGIN_WITH_CIDAAS":
case "LOGIN_WITH_SOCIAL":
console.log("User logged in Cidaas ");
console.log(userInfo);
callback(null, {
data: "done",
status: HttpStatus.OK
});
break;
default:
console.log("Un handled events ");
callback(null, {
data: "done",
status: HttpStatus.OK
});
break;
}
});
});
} catch (error) {
callback(null, {
error: userInfo.error,
status: HttpStatus.INTERNAL_SERVER_ERROR
});
}
}
}, function(error, results) {
if (results.handlewebhook.status == HttpStatus.OK) {
return res.status(results.handlewebhook.status).send(results.handlewebhook.data);
} else {
return res.status(results.handlewebhook.status).end();
}
});
});
};
