API

Velpic WebHooks API

Overview

WebHook integration provides Velpic with a way of communicating real-time information to third-party applications using HTTP callbacks.

Specification

WebHooks make HTTP POST requests to send data in real-time. This is advantageous over traditional API’s which require frequent polling, a process that can be less efficient. Messages are sent in JSON format.

Create a WebHook

WebHooks can be created through the Velpic App. To create a WebHook, follow the steps below

Step 1: Navigate to the Integration Page

In the app, navigate to the Integration tab under "Manage"

Please Note: Not all subscription levels have access to the integrations tab. If you do not see this tab, you can contact team@velpic.com to enquire about having integrations enabled

Step 2: Navigate to the WebHooks page

The options that you see here will differ according to your subscription level, but the one you want is "WebHooks". Click on that

Step 3: Add a URI

Once in the integrations page, you will see an input for the WebHook URI. This is the address that the event posts will be sent to. Enter your desired URI here.

Step 4: Select an Event Type

You will also see a dropdown for the types of events for which messages will be posted. A list of these events and their payloads can be found in the Events section below

After selecting your event type, click the add button. The WebHook setup is now complete.

You can now add more WebHooks to your account. There is no limit to the number of WebHooks you can set up.

Delete a Webhook

WebHooks can be deleted from the WebHooks page. Simply click the trash icon beside the WebHook that you wish to delete

When a WebHook is deleted, it is inactivated and will not generate ay new posts.

WebHook Events

A WebHook can be assigned one of many different events. This section describes these events, what triggers them, and what is sent to the WebHook address.

All Events

This event will trigger whenever any of the events in this section trigger.

Since there is no single event that will cause the WebHook to fire, there is no standard format for the post. Any handler would need to be able to accommodate all of the events below. However, all events have a name element which defines which event is fired


PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "lesson.schedule.completed",
    "lessonScheduleId": 1233,
    "userId": 1023,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

Lesson Schedule Completed

Lesson Schedule Completed
POST

This event fires when a user completes a lesson schedule

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "lesson.schedule.completed"
lessonScheduleId The ID number of the lesson schedule that was completed
userID The ID number of the user that completed the lesson schedule
timeStamp The time at which the event was fired

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "lesson.schedule.changed",
    "scheduleDate": "2017-01-20T01:33:27.012Z",
    "lessonScheduleId": 1233,
    "userId": 1023,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

Lesson Schedule Changed

Lesson Schedule Changed
POST

This event fires when a lesson schedule is changed. If a schedule assigned to multiple users is changed, the event will fire for each user.

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "lesson.schedule.changed"
scheduleDate The new start date for the schedule.
lessonScheduleId The ID number of the lesson schedule that was changed
userID The ID number of the user that is assigned to the lesson schedule that was changed
timeStamp The time at which the event was fired

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "lesson.schedule.created",
    "lessonScheduleId": 1233,
    "userId": 1023,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

Lesson Schedule Created

Lesson Schedule Created
POST

This event fires when a lesson schedule is created. If a schedule assigned to multiple users is created, the event will fire for each user.

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "lesson.schedule.created"
lessonScheduleId The ID number of the lesson schedule that was created
userID The ID number of the user that is assigned to the new lesson schedule
timeStamp The time at which the event was fired

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "lesson.schedule.created",
    "lessonScheduleId": 1233,
    "userId": 1023,
    "cancellationReason": "SCHEDULE_CANCELLED_MANUALLY",
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

Lesson Schedule Cancelled

Lesson Schedule Cancelled
POST

This event fires when a lesson schedule is cancelled. If a schedule assigned to multiple users is cancelled, the event will fire for each user.

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "lesson.schedule.cancelled"
lessonScheduleId The ID number of the lesson schedule that was cancelled
userID The ID number of the user that was assigned to the cancelled lesson schedule
cancellationReason The reason the lesson was cancelled. See the table below for possible values.
timeStamp The time at which the event was fired

Cancellation Reason Table

The table below lists all values that the cancellationReason field can take, as well as what they represent

Value Descriptiom
SCHEDULE_CANCELLED_DUE_TO_EMPLOYEE_TERMINATED The lesson schedule was cancelled because the employee was inactivated or otherwise removed from the system
SCHEDULE_CANCELLED_MANUALLY The lesson schedule was manually cancelled by an administrator
SCHEDULE_CANCELLED_DUE_TO_LIBRARY_REMOVAL The lesson schedule was manually cancelled because the lesson was removed from the system

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "user.account.created",
    "firstName": "John",
    "lastName": "Smith",
    "userName": "j.smith",
    "userId": 1023,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

User Account Created

User Account Created
POST

This event fires each time a user is created.

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "user.account.created"
firstName The first name of the created user
lastName The last name of the created user
userName The userName of the created user
userId The ID number of the created user
timeStamp The time at which the event was fired

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "user.settings.updated",
    "userId": 1023,
    "actingUserId": 1055,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

User Settings Updated

User Settings Updated
POST

This event fires whenever a user's settings are changed.

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "user.settings.updated"
userId The ID number of the modified user
actingUserId The ID number of user that changed the settings
timeStamp The time at which the event was fired

PostsExample
Headers
Content-Type: application/json
Body
{
    "name": "user.account.inactivate",
    "userName": "j.smith",
    "userId": 1023,
    "timeStamp": "2017-01-16T01:33:27.012Z"
}
                        

User Account Inactivate

User Account Inactivate
POST

This event fires whenever a user will be inactivated

The fields in the body of the post are as follows;

key description
name The name of the event. For this event it is always be "user.account.inactivate"
userName The username of the user that will be inactivated
UserId The ID number of user that will be inactivated
timeStamp The time at which the event was fired