Skip to main content
Version: Insiders

Approvals

Approvals offer flexible integration options. You can choose to receive notifications when an approval stage changes or specify the approvers for each approval step before starting an approval process.

State changes​

This webhook triggers whenever the state of an approval request changes, including:

  • Approval request creation
  • Approval request rejection
  • Approval request approval

HTTP Request​

POST YourApiUrl
Content-Type: application/json

{
 "requestId": "d12773f8-6ea1-42be-9be4-3cd58bac3b63",
 "title": "Group sample",
 "reason": "Is there no reason?",
 "requestorId": "d3f0fe0f-ad34-4eb2-af61-953ea3a76031",
 "participants": [
   "d3f0fe0f-ad34-4eb2-af61-953ea3a76031"
 ],
 "stage": 0,
 "totalStages": 2,
 "templateId": "8884dca2-6f58-4175-81a2-3504f6ee616d",
 "tenantId": "1840b34e-6fe7-4a56-9ad3-0b7b58c49dc7"
}

Response​

A status 200 OK is expected with no body.

Assign approvers to an approval stage​

Approval workflows often require specific approvers. In such cases, approver webhooks prove invaluable. When an approval request is initiated, the webhook calls a designated endpoint. The returned user IDs are then verified as collaborators and assigned as the approvers for that particular approval stage.

The payload content varies depending on the specific resource being requested. This ensures that the endpoint receives all necessary information to correctly determine the approvers for each case.

HTTP Request​

POST YourApiUrl
Content-Type: application/json

{
 "title": "someuser.lastname@mycompany.com",
 "reason": "Need to invite this user for our project",
 "requestorId": "d3f0fe0f-ad34-4eb2-af61-953ea3a76031",
 "state": 1,
 "guestRequest": {
   "userRequest": {
     "secondaryOwner": {
       "id": "171694ef-a2e7-4664-b6d1-ffabefc20b93",
       "userType": "Member",
       "userPrincipalName": "A20240628RMB@mydomain.com",
       "displayName": "A20240628RMB",
       "createdDateTime": "2024-06-28T13:54:28+00:00",
       "businessPhones": [],
       "accountEnabled": true,
       "mail": "A20240628RMB@mydomain.com",
       "metadataExtension": {
         "tId": "486a90c1-ff54-4cec-b9b3-c9cfe1d0f43e",
         "additionalData": {
           "tId": "486a90c1-ff54-4cec-b9b3-c9cfe1d0f43e"
         }
       },
       "policyExtension": {
         "pId": "b6307180-f8e2-48e6-b640-e1c2604c8ed7",
         "noEsca": false,
         "owSta": "compliant",
         "coSta": "compliant",
         "coCh": "2024-06-28T21:59:59+00:00"
       },
       "onPremisesExtensionAttributes": {}
     },
     "mail": "someuser.lastname@mycompany.com",
     "templateId": "4ed5368c-5fe0-41df-b739-57819614a475",
     "requestor": {
       "id": "d3f0fe0f-ad34-4eb2-af61-953ea3a76031",
       "userType": "Member",
       "userPrincipalName": "inivitee@mydomain.com",
       "givenName": "Firstname",
       "displayName": "Lastname",
       "createdDateTime": "2021-06-14T04:53:35+00:00",
       "companyName": "EasyLife",
       "businessPhones": [],
       "accountEnabled": true,
       "mail": "inivitee@mydomain.com",
       "surname": "surname",
       "preferredLanguage": "en-US",
       "officeLocation": "someoffice",
       "onPremisesExtensionAttributes": {}
     },
     "metadata": {
       "tId": "4ed5368c-5fe0-41df-b739-57819614a475",
       "color":"blue",
       "company":"easylife365"
     },
     "addToGroups": [
       "4dc6a38a-6209-42e7-ba69-c5d560e4c2e4"
     ],
     "reason": "Need to invite this user for our project",
     "sendInvitationMail": true
   },
   "requestId": "df798db9-eeb3-4b1f-94be-b4bfb99d6a70",
   "tenantId": "1840b34e-6fe7-4a56-9ad3-0b7b58c49dc7",
   "isInvitation": false
 },
 "participants": [
   "d3f0fe0f-ad34-4eb2-af61-953ea3a76031"
 ],
 "stage": 0,
 "totalStages": 0,
 "resourceType": 3,
 "approvalResourceType": 1,
 "Key": "ccf96a0c-7ea0-42fd-b540-5c6f6bd8d9d1",
 "TenantId": "1840b34e-6fe7-4a56-9ad3-0b7b58c49dc7"
}

Response​

EasyLife expects a HTTP 200 OK with an array of user Entra ID object IDs in the following format:

[
  "974d3b91-22dd-4851-9987-10ebbfb08737",
  "bb87b3cf-9d8e-4dfc-b9e6-aba0f9b4acb7"
]
warning

IDs that cannot be located in your Entra ID will be skipped. If no users can be identified, the approval workflow will terminate, and the requestor will be notified of the failure.