API Queries
Make an Endpoint Request
IsOn24 API is REST based. This means all API requests are sent via GET/POST to the following URL:https://exapi.IsOn24.com/exapi/v2
To make a successful request you must include a header with the Authorization key, and a value consisting of the access token you received via the OAuth 2.0 flow prepended with the word 'bearer'. See the example curl request below.
curl -X POST -H "Authorization: Bearer <ACCESS_TOKEN>" "https://exapi.IsOn24.com/exapi/REST"
Assuming the access token is valid, the API will process the request according to its API specifications. The API will return a 401 "invalid_request" error if the access token is invalid.
Setting up Webhooks
Webhooks allow for near-real-time data to be sent to your application when an event occurs on models within IsOn24.Webhooks are configured at the application level and will trigger when an account with an installation performs the topic. As an example, if you've configured a webhook to listen to appointment_create, whenever a user creates a new appointment, the URL provided will be sent a POST request with the details in the body. To see what details are sent, see the payload section.
It is the responsibility of the app developer to monitor that all entered Webhook URLs can successfully receive an HTTP request. IsOn24 Developer Center does not currently send automated notifications for unexpected Webhook responses (eg. HTTP status codes outside of the 2xx range).
Authorization
To receive webhook data for a topic, you must have the appropriate read scope. For example, you must have access to read appointments to access any of the appointment_x topics.
Supported Topics
To see a list of supported topics, see the New App screen. All supported topics are selectable when creating a webhook in your application's configuration.Examples:
appointment_create
appointment_update
appointment_destroy
Webhook Payload
The content type for webhooks is always in the application/json type.
Example:
{
"data": {
"event": {
"topic": "app_connect",
"appId": "5f6b0e8b9a1d8c0001a5e5d6",
"businessId": "5f6b0e8b9a1d8c0001a5e5d7",
"occuredAt": "2020-09-23T18:00:00.000Z",
"payload": {
"business": {
"id": "5f6b0e8b9a1d8c0001a5e5d7",
"name": "Test Business",
"phone": "1234567890",
"email": "some@example.com",
"timezone": "America/New_York",
},
},
}
}
Verify the Authenticity of the Webhook
Before you respond to the webhook, you should verify that the webhook was sent from IsOn24. A calculated signature is sent with every webhook, which you can use to verify the authenticity of the request.Each request will include a base64 encoded X-IsOn24-Hmac-SHA256 header, generated using your app's OAuth client secret and the data sent in the webhook.
Here is an example in JavaScript as to how one might verify the request:
const { timingSafeEqual, createHmac } = await import('node:crypto');
export function verify_webhook_signature(signature, payload) {
const hash = createHmac('sha256', CLIENT_SECRET)
.update(payload)
.digest('base64');
// return signature === hash;
return timingSafeEqual(Buffer.from(signature), Buffer.from(hash));
}
export function verify_webhook_payload(req) {
/*
req.headers
{
…
"x-ison24-hmac-sha256": "zIwGfSFFS2VA2VoXB3lS2lDUTmRMvWIeiunQ5LeyXpU="
}
*/
// Extract Header X-Jobber-Hmac-SHA256
let hmac = req.headers['x-ison24-hmac-sha256'];
if (!hmac) {
let err = 'No HMAC found';
logger.warn(err);
throw new Error(err);
}
logger.debug(`HMAC: ${hmac}`);
// Check for payload
if (!req.body) {
let err = 'No body found';
logger.warn(err);
throw new Error(err);
}
const body = req.body;
// logger.debug((typeof body));
const body_str = JSON.stringify(body);
// logger.debug(body_str);
// logger.debug( body.toString() );
// utils.logObject(body);
let res = verify_webhook_signature(hmac, body_str);
if (!res) {
let err = 'Webhook verification failed';
logger.warn(err);
throw new Error(err);
}
return body;
}