Introduction
This document covers the area of using web hooks as method to integrate with the Sequel platform to receive platform events of interest. Web hooks allows the clients to use event driven approach to trigger workflows instead of using long polling mechanisms.
Sequel events available for Web Hooks
The following events are current available for web hooks:
- Virtual Stage Event Started (
virtual-stage-event-started) - Virtual Stage Event Ended (
virtual-stage-event-ended) - New Attendee Pre-registration (
new-attendee-pre-registration) - Event Created (
virtual-stage-created) - Event Updated (
virtual-stage-updated) - Event Deleted (
virtual-stage-deleted)
Virtual Stage Event Started
This event is triggered when the stream for the event starts, usually triggered by the host with a click on the "Go Live" on the virtual stage.
The web hook subscribing to this event receives the event and company information for the event that went live.
Virtual Stage Event Ended
This event is triggered when the stream for the event is ended, usually triggered by the host with a click on the "End Event" or "End Event and Start Networking" button on the virtual stage.
The web hook subscribing to this event receives a list of users (hosts, presenters and attendees) for the event when the event ends. The user data starts from start date of the event.
New Attendee Pre-registration
This event is triggered when an attendee registers for a virtual stage event which is configured for pre-registration.
The web hook subscribing to this event receives the attendee information name, e-mail and responses to any custom questions configured for the event.
Managing Web Hook Subscriptions
This section describes the various operations available to mange web hooks. The operations available are as follows:
- Registering a web hook
- Retrieving web hook information
- Editing a web hook
- Renewing a web hook
- Unregistering a web hook
Subscription Length
Following the recommend practice for web hook subscriptions to have an expiration date, by default, the Introvoke web hook subscription will expire in 90 days. The web hook subscription length can be between 2 - 365 days.
Operations
Base url
The base url for all webhooks events is
<https://api.introvoke.com>
Registering a web hook
The web hook can be registered by making a request to the following endpoint on Introvoke API.
| HTTP method/endpoint | POST /api/integrations/webhooks |
|---|---|
| Authentication | JWT for Introvoke API (Request header) |
| Request Body | {"eventType": "Introvoke event type. Example: virtual-stage-event-ended","subscriptionInfo": {"companyId": "unique id of the company","eventId": "unique id of the event (optional)","endpoint": "web hook endpoint to POST data to","subscriptionLengthInDays": (optional) - 2-365, default: 90}} |
| Responses | HTTP 201 - subscription created for the event and length if specified, else 90 days. Response Body: {"webHookSubscriptionId": "unique id of the subscription","clientSecret": "secret phrase","expiresOn": "date for subscription expiration"} |
| Other Responses | HTTP 400: If event type is not valid or subscription length is not within range HTTP 404: If the company does not exist or user does not have access to it. |
IMPORTANT
The client must take note of the client secret and store it safely. It will not accessible to the client after the request.
Retrieving a web hook
The information about the web hook subscription can be retrieved by making a request to the following endpoint on Introvoke API.
| HTTP method/endpoint | GET /api/integrations/webhooks/:webHookSubscriptionId |
|---|---|
| Authentication | JWT for Introvoke API (Request header) |
| Path/Query Parameters | |
| Request Body | N/A |
| Responses | HTTP 200Response Body:{"webHookSubscriptionId": "unique id of the subscription","subscriptionInfo": {"eventType": "Introvoke event type""companyId": "unique id of the company","eventId": "unique id of the event","endpoint": "web hook endpoint to POST data to","expiresOn": "date for subscription expiration"}} |
| Other Responses | HTTP 404: If the web hook subscription id does not exist or user does not have access to it. |
Editing a web hook
The web hook subscription can be updated by making a request to the following endpoint on Introvoke API.
| HTTP method/endpoint | PUT /api/integrations/webhooks/:webHookSubscriptionId |
|---|---|
| Authentication | JWT for Introvoke API (Request header) |
| Path/Query Parameters | |
| Request Body | {"subscriptionInfo": {"endpoint": "(optional) web hook endpoint to POST data to","extendSubscriptionByDays": (optional) number of days to extend the subscription. Values 2-365, default: 0}} |
| Responses | HTTP 200 Response Body: {"webHookSubscriptionId": "unique id of the subscription","subscriptionInfo": {"eventType": "Introvoke event type""companyId": "unique id of the company","eventId": "unique id of the event","endpoint": "web hook endpoint to POST data to","expiresOn": "date for subscription expiration"}} |
| Other Responses | HTTP 404: If the web hook subscription id does not exist or user does not have access to it. |
Renewing a web hook
The web hook subscription can be renewed by making a request to the following endpoint on Introvoke API.
| HTTP method/endpoint | POST /api/integrations/webhooks/renew/:webHookSubscriptionId |
|---|---|
| Authentication | JWT for Introvoke API (Request header) |
| Path/Query Parameters | |
| Request Body | Request body is optional{"subscriptionInfo": {"subscriptionLengthInDays": (optional) number of days to renew the subscription. Range: 2-365, default: 90}} |
| Responses | HTTP 200 Response Body: {"webHookSubscriptionId": "unique id of the subscription","clientSecret": "new secret phrase","expiresOn": "date for subscription expiration"} |
| Other Responses | HTTP 404: If the web hook subscription id does not exist or user does not have access to it. |
IMPORTANT
Renewing the web hook subscription will cause a new client secret to be issued. The client must take note of the client secret and store it safely. It will not accessible to the client after the request.
Unregistering a web hook
The web hook subscription can be renewed by making a request to the following endpoint on Introvoke API.
| HTTP method/endpoint | DELETE /api/integrations/webhooks/:webHookSubscriptionId |
|---|---|
| Authentication | JWT for Introvoke API (Request header) |
| Path/Query Parameters | |
| Request Body | None |
| Responses | HTTP 200 : when the subscription is unregistered Response Body: {"webHookSubscriptionId": "unique id of the subscription",} |
| Other Responses | HTTP 404: If the web hook subscription id does not exist or user does not have access to it. |