API v2 - Webhooks

API v2 Webhooks

1 What are Webhooks?
- 1.1 Webhooks overview
- 1.2 Benefits of using Webhooks
- 1.3 Webhooks use cases
2 How to create Webhooks
3 Generate POST requests with Webhooks to send data when a new item is created
4 Generate PUT & PATCH requests with Webhooks to send data when items are updated
5 Generate DELETE requests with Webhooks to send data when items are deleted
6 Tracking & managing your triggered Webhooks with Webhook instances
7 FAQs
8 Support

Related Help Guide Pages

Integrate with the accessplanit API v2 Feeds - Overview

This page covers how to use the Webhooks which are available as a part of the API v2 module.

Welcome to our Webhooks guide! This page explains how to access and utilise the Webhooks functionality for accessplanit’s API v2 feeds.

Here’s what you’ll find within this guide:

What are Webhooks
An overview of what Webhooks are, and some key uses for integrations
How to create Webhooks
How to create Webhooks in your accessplanit platform
FAQs and further support
Answers to commonly asked questions about the Webhooks, and how you can get in touch with our team for any additional support.

Follow this page to access the developer information for using the accessplanit v2 APIs.

What are Webhooks?

The section covers the purpose and ways that you can use Webhooks

Webhooks overview

Webhooks are a way for two applications/systems to communicate and exchange information in real-time, without needing to rely on constant requests for updates.

Webhooks are essentially automated notifications, that are triggered by specific events that you can define. They instantly send data from your accessplanit platform to another system, such as a finance system, a HR system or a CMS. For example, Webhooks could be used to push updates, like course registrations, or payment completions, to your other systems as soon as they happen!

Benefits of using Webhooks

Here is why Webhooks may be used, instead of direct querying the API v2 feeds, or using another method for accessing data such as automated exports.

Real-time updates
The biggest benefit of using Webhooks is that data can move immediately from your accessplanit platform when an event happens, this means that there is no need to wait for regular imports or manual syncs.

For example, as soon as a Course has been scheduled a Webhook can be triggered to share this data with another system, rather then waiting for an export file to be generated, or a periodic sync of data.

Simplified integration

While technical and integration knowledge is required, with Webhooks you can connect systems without the need for extensive coding, this means that there is a lot more flexibility for the integrations without requiring in depth technical know-how, while also reducing the potential for human error.

Improved data accuracy
As data is moving in real-time, it means that your integration is always working with the latest information, ensuring you have accurate and timely information across all of your integrated systems.

Webhooks use cases

There are plenty of ways Webhooks can be used to connect your accessplanit platform with other software! Here are some examples:

Finance & Accounting Systems

Event in your accessplanit platform	Webhook purpose
Invoice is generated	Send details of the invoice to the accounting system
Payment/refund is recorded	Send details of the transaction to the accounting system
PO Number on an Invoice has changed	Send the updated PO Number to the accounting system
Invoice is cancelled	Send the updated status about the invoice to the accounting system
Credit Note is generated	Send details of the credit note to the accounting system

HR Systems

Event in your accessplanit platform	Webhook purpose
New User is added	Send details of the user to the HR system
User registers onto a Course as a Delegate	Send details of the delegate to the HR system
User is targeted an Award	Send details of the training target to the HR system
Delegate is marked as ‘completed’ on a Course	Send details of the course completion to the HR system
User has their status changed to ‘inactive’	Send the updated status about the user to the HR system

Virtual Learning Environments (VLEs)

Event in your accessplanit platform	Webhook purpose
New Course is scheduled	Send details of the course to the VLE
Webinar Course joining information is updated	Send the updated JI for the course to the VLE
A Course is cancelled	Send the updated status about the course to the VLE
Delegate is marked as ‘completed’ on a Course	Send details of their course completion and their score to the VLE

Website/CMS

Event in your accessplanit platform	Webhook purpose
New Course is scheduled	Send details of the course to the CMS so it can be advertised for bookings
A Course is cancelled	Send the updated status about the course to the CMS so it can be removed
A Course becomes fully booked	Send the updated status about the course to the CMS so it can be shown as full

Please Note

If you are sending across User data, for example when a new User is created, or an existing User is updated, the data may be sent across two feeds. This is because some User information is stored within ‘Users’ (such as the first name and last name), and further information is stored within ‘UsersDetails’ (such as email address).

How to create Webhooks

The section covers the basic steps for creating Webhooks in your accessplanit platform, please note that more details information is available later in this guide.

Access to create Webhooks

These are the requirements to be able to access the Webhooks functionality in your accessplanit platform

To gain access to create and manage Webhooks…

Your accessplanit platform must have the API v2 module enabled
Your User requires an additional role to provide you with access to the page

As API access is an additional module, to request access to Webhooks, please contact the Customer Success team at accessplanit, the team here will arrange for the required Users to have the additional role assigned to them as a part of this process.

Create a Webhook

Here is an overview of the steps to create a Webhook, more detailed information is available further down this page.

Open the ‘Administration’ menu from the Profile options at the top-right of your platform
Open the ‘Webhooks’ menu option to access the Webhooks DataGrid where you can add and manage Webhooks
From the Webhooks DataGrid, click the ‘Add Webhook’ button
Provide your Webhook with a label
We recommend that the label includes the integration that the Webhook is for and the event that will trigger it, such as ‘Website Integration - New Course Scheduled’
Provide a description for your Webhook
This should be as detailed as possible to support your team understanding the purpose of this Webhook
Leave your Webhook as inactive for now
Select the platform module where your Webhook will retrieve data from
The modules in the drop-down list are labelled using the module’s API name followed by the module’s platform name in brackets, this means that this list can be understood by both API developers and platform users.
Select the trigger event for your Webhook
1. Create - only trigger the Webhook when a new item is created (e.g. a new Course is scheduled)
2. Update - only trigger the Webhook when an existing item is updated (e.g. an existing Course has had changes made to it)
3. Create Or Update - trigger the Webhook when an item is created or updated (e.g. a new Course is scheduled or an existing Course has had changes made to it)
4. Delete - trigger the Webhook when an item is deleted (e.g. a Course is deleted from the platform)
Define the rules for your Webhook triggering by adding conditions
For example, to only display advertised, future Courses that have a status of Fully Booked or Available on your website, the following conditions would be required:
Provide the endpoint for where the Webhook should send the data
Select the HTTP method for your Webhook
1. GET - GET may be used to fetch the current state or details of an item however this method is not commonly used with Webhooks,
2. POST - POST is used to create a new record/item in your integrating system, e.g. create a record of a new Course
3. PUT - PUT is used to update all of the details of an item in your integrating system, e.g. every bit of information about a Course is updated/refreshed
4. PATCH - PATCH is used to update specific details of an item in your integration system, e.g. update the ‘status’ and ‘remaining places’ for a Course
5. DELETE - DELETE is used to remove items/records in your integration system, e.g. delete a Course
If you select Post, Put, or Patch for the Method, you then must decide what data is shared with the integrating system about the item
1. ID Only = only the ID of the created/updated item will be provided to the integrating system
2. ID And Modified Fields = only the ID and the fields that have changed as a part of the latest item update will be provided to the integrating system
3. Selected Fields = you can select which fields are provided to the integrating system
4. Custom = you can write your own extract (such as XML) including merge fields which will get posted as a data package (more information and examples are available lower down in this guide)
Click the ‘Save’ button to create your Webhook
If you are ready to start using or testing your Webhook, set the Webhook to be ‘Active’ and Save again

Please see below for more detail on each type of Webhook command

Testing your Webhook using Webhook.site

Here is an overview of how you can test your webhook is providing the right information at the right time

If your integrating software isn’t quite ready or doesn’t yet have an endpoint to work with, you can use Webhook.site as a handy listener tool. This service generates a unique URL you can use as a temporary endpoint for your webhook. Once set up, you can track and review the webhook data directly on the Webhook.site page, making it a great way to test and troubleshoot your integration setup.

Do not test with real data

When testing with Webhook.site, we strongly recommend using anonymous User data and made-up Course data wherever possible. Avoid sending any sensitive personal data to ensure your tests remain secure and compliant with data protection regulations.

Generate POST requests with Webhooks to send data when a new item is created

The section covers how to create POST Webhooks to instruct your integrating system to create a new record/item.

When a new item is created in your platform, for example a new Invoice is generated, a new Course is scheduled, or a new User is added, you may wish to send the details of this new item to an integrating system. Typically, the HTTP method of ‘POST’ is used for these events,

For this section, we will use the example of a new Delegate being created (a User has been added to a Course).

Within your new Webhook, provide a useful label and description
Select the appropriate module for where the data is coming from, in this case we want the ‘Delegate’ module which is known as the ‘UserCourseDate’ module within the API Feeds
Select the appropriate trigger, in this case we want ‘Create’ because we want to generate the Webhook when a Delegate is created
Define the conditions of your Webhook, in this case we only want the Webhook to trigger when a new Delegate is created with the Type of 'Delegate' (e.g. exclude Trainers on the Course), with a Status of ‘Completed', ‘Provisional’, ‘In Progress’, or 'Booked, and they are not booked onto a Session
Provide the Endpoint URL for where the webhook data will be sent to
Select the HTTP Method of 'POST'
Select what data you would like to send about the new item (in this case the new Delegate)
For new item POST events, we would recommend ‘Selected Fields’ or ‘Custom’
If you are using ‘Selected Fields’, select the fields you would like to include in the integrating data
If you are using ‘Custom’, enter your custom integration code into the text box
Save your Webhook

Custom Data Top tip!

To find the merge field text for the fields that are available for a module, open a new tab and navigate to the Email Templates DataGrid in Administration, create a new Email Template, select the relevant module, and add the fields that you would like to include in your Custom Data into your Email as a merge field e.g. ‘Delegate First Name’, you can then copy the merge field text e.g. ‘@@CandidateForename’.

Generate PUT & PATCH requests with Webhooks to send data when items are updated

The section covers how to create PUT and PATCH Webhooks to instruct your integrating system to update the details of an existing record/item.

When an existing item is updated in your platform is updated, for example an Invoice is assigned a PO Number, a Course changes status from ‘Available’ to ‘Cancelled’, or a User updates their contact information, you may wish to send the details of these changes to an integrating system. Depending on your integration requirements, you may use a PATCH or a PUT method for these events.

For this section, we will use the example of a Delegate having their attendance and score set after a Course has run.

Within your new Webhook, provide a useful label and description
Select the appropriate module for where the data is coming from, in this case we want the ‘Delegate’ module
Select the appropriate trigger, in this case as we want ‘Update’ because we want to generate the Webhook when existing Delegates are updated
Define the conditions of your Webhook, in this case we only want the Webhook to trigger when a Delegate has had their status changed to ‘Completed’ or ‘No Attend’
Provide the Endpoint URL
Select the HTTP Method of ‘PUT' or 'PATCH’
Select what data you would like to send about the updated item (in this case the updated Delegate)
1. ID only - use this option if you only need to provide the ID of the item that has been changed and no additional information is needed; e.g. a Course that has been cancelled, only the ID is needed to cancel/remove the Course from the integrating system
2. ID And Modified Fields - use this option where you only need to provide the information that has been updated as a part of the items latest update
3. Selected Fields - use this option if you would like to choose what fields are provided
4. Custom - use this option to write your own extract (e.g. in XML)
If you are using ‘Selected Fields’, select the fields you would like to include in the integrating data
If you are using ‘Custom’, enter your custom integration code into the text box
Save your Webhook

Generate DELETE requests with Webhooks to send data when items are deleted

The section covers how to create DELETE Webhooks to instruct your integrating system to remove the details of an existing record/item.

When an item is deleted in your platform, for example a User is deleted or a Course is deleted, you may wish to send the details of this deletion to an integrating system.

For this section, we will use the example of a deleted Delegate.

Within your new Webhook, provide a useful label and description
Select the appropriate module for where the data is coming from, in this case we want the ‘Delegate’ module
Select the appropriate trigger, in this case as we want ‘Delete’ because we want to generate the Webhook when existing Delegates are deleted from the platform
Define the conditions of your Webhook, in this case we do not wish to apply any conditions, because there is no longer data stored about the deleted Delegate to be used as rules for the webhook (only the ID of the item will be available to share via the webhook)
Provide the Endpoint URL
Select the HTTP Method of ‘DELETE'
Save your Webhook

Tracking & managing your triggered Webhooks with Webhook instances

Webhook Instances are created each time a Webhook’s criteria is met, you can check these instances to see if your data was transferred successfully.

Where to find Webhook Instances

Each Webhook in your platform has it’s own list of Webhook Instances, these can be found by clicking on the ‘Instances’ option in the Webhook Maintenance Management Menu.

Within the DataGrid you can see each Instance, and whether it was successful (Completed) or failed.

Viewing your own Response Codes & Messages

The Webhook Instances page has a standard column included which displays the message received back alongside the status.

If a message is provided back; e.g. alongside a 200 Status Code there is the message “Your request was successful”, this will be available to report on in your DataGrid.

Retriggering Webhook Instances

Retriggering Webhook Instances can be especially helpful during your testing phase, you can retrigger both successful and failed instances as you make changes to your integration.

To retrigger an Instance:

Open the Instances page for your Webhook
Find the Instance you would like to retrigger
Right-click on the Instance to view the Context Menu options
Click on the ‘Re-trigger’ context menu option
Confirm the Re-trigger
The Webhook will have triggered again, and you will see that the ‘Attempts’ has increased by one

Webhook Instances further information

The maximum number of attempts that your accessplanit platform will try per Instance is 5, you are able to retrigger Instances manually passed this attempt limit.

FAQs

Here are answers to the common questions we receive about Webhooks

Why do PATCH and PUT have the same options available?

Where can I find the '@@' merge fields for my custom post data?

Can I edit a Webhook after I have created it?

Can I delete a Webhook after I have created it?

Can I provide access to webhooks to additional Users?

Support

If you need any further support with building integrations using the Webhooks, here are the steps to get in touch with us

If you have any questions or need any further support with building and using Webhooks, please ask an administrator with support desk access to raise a ticket directly with our support team.

Please include details about what you are looking to achieve (e.g. send user information)
Please include details about the requests you have tried (e.g. any errors you are seeing, if the data is arriving)
Please let us know the name of the system(s) you are looking to integrate with

Knowledge Base