Webhooks allow for two way integration of user specific information with 3rd party systems. This article will show you how to setup and configure them to your needs.
What are webhooks?
A webhook is a user defined HTTP callback which is triggered when a specific event occurs within the Contensis application, services or on a published website.
When an event occurs, a HTTP request is made to a user defined URL with information relating to the event.
Contensis webhook events
The webhooks feature is currently limited to user specific information, so a typical event will carry the following information:
- Type of event that occurred (e.g. user registered, user logged in or off, user profile update)
- User specific information (e.g. username, firstname, email, address etc)
- Time of event
This information is transmitted via HTTP, to enable 3rd party systems to be notified when these types of events happen, together with all the information surrounding a user object within Contensis.
Possible use cases
A webhook would allow developers to:
- Create a CRM record for a new registered user
- Ensure that a HR system is updated when a user of an intranet changes their details
- Notify an email campaign system when a user has updated their preferences
3 different contexts
A webhook can be sent from any 3 locations within Contensis.
- CMS Server - when a system administrator updates a user, or an editor logs in for example
- Services Server - active directory synchronisation service has the potential for updating Contensis user profiles based on active directory changes
- Published website - your registered users will register, login, logoff and update their profile throughout their membership lifetime with your site.
This is useful to know as each one of these setups has slight differences in their configuration to allow webhooks to be configured in a flexible way.
Setup and configure webhooks
You can enable webhooks to be sent when activity happens to a user object within the CMS by adding a URL to the global setting WebHooks_CMS_UserWebHookUrl
Giving this a URL means that for each of the following actions, the URL will be requested with the user object data:
- User logging in to the CMS
- User logging out of the CMS
- New user created in the CMS
- User details updated within the CMS
- User deleted within the CMS
The only Contensis Windows Service that has an interaction with the user object is the Active Directory Synchronisation service. This uses the same setting as the CMS server to determine the URL to request: WebHooks_CMS_UserWebHookUrl
There is also a flag that can be overridden within the service called SendWebHooksFromDirectoryServices which lives within the ContensisDirectoryServicesService.exe.config file on your Contensis Services server. Typically this can be found in C:\Program Files (x86)\Contensis\contensis services\.This allows you to suppress the service sending any webhooks.
Please note that if the global setting DirectoryServices_DeleteInvalidUsersAndGroups is set to False, then users are not actually removed from the CMS, but are only Locked and Disabled, therefore the Security.User.Delete webhook will never fire.
The setting to enable webhooks on a published website can be found in the CMS Config against each of the publisher servers in your project. This provides more granularity than using the global setting; allowing you to disable the feature on a preview servers, and enable it on live servers.
The name of the setting is WebHooks_Website_UserWebHookUrl. Setting this to the URL you would like to react to user object changes will mean it will receive HTTP requests for:
- User logging in to the website
- User logging out of the website
- New registered user created in the website
- Registered user detail updated within the website
As this setting is applied against the publishing server, you can decide whether preview and live servers have different configurations to aid debugging issues.
A basic example
In order to give a basic example, we will create a webhook for our front end website.
1. Create the Subscriber ApiController
Create a ContensisApiController within your App_Code folder which will be responsible for handling the webhook. This is an example of one:
This very simple example is just creating a ContensisApiController and using Attribute Based Routing to bind to a route of /api/Webhooks/SampleEndPoint. Any request that comes into this route will have its data deserialized into type of WebHookResponse.
All webhooks will ensure that this type is serialized and deserialized correctly so that is as simple to consume as possible. So the SampleEndPoint method just received the WebHookResponseData and adds it to a static list of webhooks. We’ll utilise this static list within a razor view in the next step.
2. Create the razor view
Now we are going to create a razor view that will simply output the contents of the WebHookResponseList purely to demonstrate the power of webhooks. Create a new Razor View and paste in the contents below:
Once you create this razor view and add it to a page, previewing it will only show “No webhooks received yet”. This is because we haven’t yet registered a URL to be requested when any user event occurs.
Register the webhook
So against a particular publishing server, enter this URL : http://[yourwebsiteaddress]/api/Webhooks/SampleEndPoint so that at the bottom of your CMS Config looks like:
On this has been set and the config file is published, each Login, Log out, new user, user update event will trigger a webhook to this URL. By refreshing the page containing the razor view, the message stating No webhooks received yet should now be replaced with a list of events that have happened within your front end website.
You can also inspect the EventType property of the WebHookResponse object to filter for specific types of events. Those currently supported are:
Also note that user object changes within the CMS will not currently result in a Http request to this same ApiController - to do this we would also need to set the Global Setting to http://[yourwebsiteaddress]/api/Webhooks/SampleEndPoint from within the Management Console.