Webhooks

Webhooks are a set of simple Web APIs that allow one application to send data and instructions to another application when an event occurs. The OptimalCloud webhooks allow SAS applications used by Optimal IdM customers to interact with the OptimalCloud.

The OptimalCloud supports the following types of Webhooks:

TICKETS – this Webhook allows SAS Helpdesk applications to send incident information to the OptimalCloud to create a ticket in the Optimal IdM Support System.
HR – this Webhook allows SAS HR applications to send user information to the OptimalCloud to create and manage user accounts.

Configuration for all Webhooks

To configure a Webhook in the OptimalCloud you must create an API Key or a Service Account.

The API Key or Service Account is used to authenticate the communication between the Client Application and the OptimalCloud.

Create an API Key

To create an API Key go to the API Key Manager on the Administration tab.

API Key Manager app

Create a new API Key and select the Management API option. See the API Key Manager section for more information.

If using this method for authentication, the API Key must be passed in the Authorization Header of the HTTP POST Request sent to the Webhook.

Create a Service Account

To create a Service Account go to the User Manager on the Identity Management tab.

User Manager app

Create a new user account specifying the name as a Service Account. See the Create New User section of documentation for more information on how to add a new user account.

If using this method of authentication, the email address and password for this Service Account must be passed in the Authorization Header of the HTTP POST Request sent to the Webhook.

TICKETS Webhooks

The TICKETS Webhook allows the SAS Helpdesk application to send incident data to create a ticket in the OptimalCloud Support system.

The Tickets Webhooks currently supported are:

ServiceNow
Generic

Configure TICKETS Webhooks

To configure the TICKETS Webhook functionality for your Tenant perform the following steps:

Create an API Key or Service account as discussed above.
Configure the SAS Helpdesk application with the TICKETS Webhook URL for your Tenant and the API Key or Service Account.

The ServiceNow TICKETS Webhook URL for your Tenant is

https://{tenant}.theoptimalcloud.com/v5.0/mgmt/api/v1.0/webhooks/helpdesk/servicenow

where {tenant} is replaced with your Tenant name.

The Generic TICKETS Webhook URL for your Tenant is

https://{tenant}.theoptimalcloud.com/v5.0/mgmt/api/v1.0/webhooks/helpdesk/createticket

where {tenant} is replaced with your Tenant name.

Use TICKETS Webhooks

To create a ticket in the Optimal IdM Support System the SAS Helpdesk application needs to send an HTTP POST request containing JSON data with information from the helpdesk ticket. Either the email address and password for this Service Account or the API Key must be passed in the Authorization Header of the HTTP POST Request sent to the Webhook.

The following fields are required fields:

Requester Email - the email address of the person from your Tenant that has an Optimal Support account and is submitting this ticket.
Short Description - the title of the ticket.
Description – the description of the incident that will be used as the body of the Optimal Support Ticket.
Priority – the priority of the incident that will be used to set the priority on the Optimal Support ticket

All other fields are optional but will be included in the first comment of the ticket if they are present.

The results of the ticket creation will be returned in the Response Code (Success – 201, Failure – 400, 401)

A successful response will include the Optimal Support Ticket number {"ticket":XXXXX}
For requests without a valid authentication a HTTP 401 response code with a generic “ERROR” message will be returned. This is for security purposes, so that hackers can not glean any information by sending invalid request.
For requests with a valid authentication, if there is an error, an HTTP status code 400 along with an specific error message will be returned. Please see each Ticket Webhook section for the specific error code messages.

ServiceNow Tickets Webhook

To send helpdesk ticket information from ServiceNow to the ServiceNow Tickets Webhook the POST Request must contain a JSON object as shown below.

{
    "requester_email": "john.doe@optimalidm.com",
    "number": "INC010100",
    "reported_by_email": "someone@optimalidm.com",
    "opened_at": "2022-01-05T19:25:51.927013+00:00",
    "impact": "low",
    "urgency": "medium",
    "short_description": "Test Ticket",
    "description": "Description of the Incident",
    "category": "network",
    "priority": "high",
    "sys_id": "9d385017c611228701d22104cc95c371",
    "subcategory": "ldap",
    "state": "open"
}

Where:

requester_email - is a required field and contains the email address of someone that has an Optimal Support Account for your tenant.
short_description - is a required field and contains the title of the ticket.
description - will be used as the body of the first ticket comment.
priority - will set the priority on the Optimal Support ticket.
all other fields are optional but will be included in the first ticket comment if they are passed in.

The following HTTP Response Codes and Error messages will be returned:

400 "requester_email is a required field"
400 "short_description is a required field"
400 "Requestor email was not found in Zendesk"
400 "Failed to create the new ticket in Zendesk"

Generic Tickets Webhook

To send helpdesk ticket information from a Helpdesk application to the Generic Tickets Webhook, the POST Request must contain a JSON object as shown below.

{
    "requester_email": "john.doe@optimalidm.com",
    "title": "Test Ticket",
    "description": "Generated by the CreateTicket webhook"
}

Where:

requester_email - is a required field and contains the email address of someone that has an Optimal Support Account for your tenant.
title - is a required field and contains the title of the ticket.
description - is a required field will be used as the text of the first ticket comment.

The following HTTP Response Codes and Error messages will be returned:

400 "title is a required field"
400 "description is a required field"
400 "requester_email is a required field"
400 "Requestor email was not found in Zendesk"
400 "Failed to create the new ticket in Zendesk"

HR Webhooks

The HR Webhooks allow the SAS HR applications to synch user data to the OptimalCloud when a new user is onboarded, modified, or terminated.

The HR Webhooks currently supported are:

Paylocity
Generic HR

Configure HR Webhooks

To configure the HR Webhook functionality for your Tenant perform the following steps:

Create an API Key or a Service Account as discussed above.
Create a Provisioning Destination

The Provisioning Destination is the instance of a provisioning plugin that synchs user data between the OptimalCloud and the client HR application.

To create a Provisioning Destination go to the Provisioning Manager on the Administration tab.

Create a New Provisioning Destination and select the type of Provisioning Destination that corresponds to your HR application.

Once the Provisioning Destination is created the HR Webhook URLs are provided on the User Provisioning tab.

Three HR Webhook URLs will be provided. Where {plugin_id} is the id of the new Provisioning Destination and {tenant} is the name of your Tenant.

Add User:

https://{tenant}.theoptimalcloud.com/v5.0/mgmt/api/v1.0/webhooks/provisioning/{plugin_id}/adduser

Modify User:

https://{tenant}.theoptimalcloud.com/v5.0/mgmt/api/v1.0/webhooks/provisioning/{plugin_id}/modifyuser

Terminate User:

https://{tenant}.theoptimalcloud.com/v5.0/mgmt/api/v1.0/webhooks/provisioning/{plugin_id}/deleteuser
Configure the SAS HR application with the HR Webhook URLs for your Tenant and the API Key or Service Account.

Use HR Webhooks

Paylocity

To use the Paylocity HR Webhooks you must configure your Paylocity HR application with the API Key or Service Account and the three Provisioning URLs.

Generic HR Webhook

To send HR information from an HR Application to the Generic HR Webhook, the HR application must send a POST Request to one of the three HR Webhook URLs provided during the creation of the Provisioning Destination based on the desired action. For authentication, either the email address and password for the Service Account or the API Key must be passed in the Authorization Header of the HTTP POST Request.

The POST Request must contain a JSON object as shown below.

{
    "employee_id": "1111",
    "first_name": "John",
    "last_name": "Doe",
    "email": "John",
    "mobile": "John",
    "display_name": "John Doe",
}

Where:

employee_id - is a required field for all operations. Uniquely identifies the employee in your organization.
first_name - is a required field to add a user. Contains the user’s first name.
last_name - is a required field to add a user. Contains the user’s last name.
email - is a required field to add a user. Contains the user’s Email address and will be used as the users login ID by default.
mobile - contains the user’s mobile number.
display_name - contains the user’s full name.

The following HTTP Response Codes and Error messages will be returned:

400 "employee_id is a required field"
400 "first_name is a required field"
400 "last_name is a required field"
400 "email is a required field"
400 "Failed to create user in the OptimalCloud"