Webhooks

Webhooks are push notifications sent by Syskit Point as HTTP requests to a registered webhook endpoint when an event occurs.

To successfully enable webhooks in Syskit Point, you need to perform the following steps:

Register endpoint to which Syskit Point will send notifications.
Obtain the signature key and secure your endpoint.
- It is recommended for your webhook handler to verify that the webhook requests are generated by Syskit Point.

You must set up an HTTP endpoint function that can accept webhook requests using a POST method.

Registering a Webhook Endpoint with Syskit Point API

Please note!
The application used to access the webhooks endpoint needs to have the Point.Admin app role.

To register a webhook endpoint via the Syskit Point API, you need to use the following POST request:

POST {{pointWebAppUrl}}/v1.0/webhooks/endpoints

Headers

Body

{% tabs %} {% tab title="Example" %}

{
  "endpoint": "https://contoso.azurewebsites.net/api/Logger?code=o74oKsbrgHDI-RnekJXdbR3Fba7mZxEmJQNyCIpV6z-ZAzFuwnaWJg==",
  "types": [
    "*"
  ]
}

{% endtab %} {% endtabs %}

You can subscribe to all event types using the * symbol, as shown in the example.

Types

Syskit Point can send the following types of events:

Below, you can find examples for all types:

{% tabs %} {% tab title="ProvisioningStarted" %}

{
    "type": "ProvisioningStarted",
    "content": {
      "name": "Resource Name",
      "type": "MicrosoftTeams|SharePointSiteCollection|YammerCommunity|M365Group",
      "requestedOn": "2023-10-05T14:48:00",
      "requesterId": "235ec2cb-0767-40b3-a1de-4da2c42b19e9"
    },
    "meta": {
      "timeStamp": "2023-10-05T14:48:00",
      "idempotencyKey": "f9ac8355-ddd7-48a3-98fb-9d4142501510"
    }
}

{% endtab %} {% tab title="ProvisioningCompleted" %}

{
    "type": "ProvisioningCompleted",
    "content": {
      "name": "Resource Name",
      "type": "MicrosoftTeams|SharePointSiteCollection|YammerCommunity|M365Group",
      "url": "https://contoso.sharepoint.com/sites/resourcename",
      "microsoftId": "3b735b14-de6f-4cf8-adc6-da7eaccbdc31"
    },
    "meta": {
      "timeStamp": "2023-10-05T14:48:00",
      "idempotencyKey": "854d127b-95c2-4b5f-bb45-7813946dee72"
    }
}

{% endtab %} {% tab title="ProvisioningFailed" %}

{
    "type": "ProvisioningFailed",
    "content": {
      "name": "Resource Name",
      "type": "MicrosoftTeams|SharePointSiteCollection|YammerCommunity|M365Group",
      "error": "Error Message",
      "correlationId ": "f65cefa6-01b7-47d6-a2cb-9442d13dd535"
    },
    "meta": {
      "timeStamp": "2023-10-05T14:48:00",
      "idempotencyKey": "45285061-1288-4899-b108-ad06cfbbcf6f"
    }
}

{% endtab %} {% endtabs %}

Response

Successful registration of the webhook endpoint results in response status 200.

{% tabs %} {% tab title="200" %}

{
    Null
}

{% endtab %} {% endtabs %}

Webhook Events

Syskit Point sends a POST request to the registered webhook endpoint URL.
The event object has the following body structure:

{% tabs %} {% tab title="Body" %}

{
    "type": "type",
    "content": {serializedContent},
    "meta": {
        "timeStamp": "timestamp",
        "idempotencyKey": "key"
    }
}

{% endtab %} {% endtabs %}

Each webhook event also sends two headers:

Signature: Contains the message signature created using the hashing algorithm provided in the Algorithm header using a signature key.
Algorithm: The hashing algorithm used to create the message signature.

Signature Validation

To verify the notification was sent by Syskit Point:

Get the signature key via Syskit Point API
Create a signature using the key to compare with the signature in the received event object

To get the signature key, send the following GET request.

GET {{pointWebAppUrl}}/v1.0/options

Response

Successful request results in response status 200 and provides the Signature Authentication Key.

{% tabs %} {% tab title="200" %}

{
    "webhooksSignatureAuthenticationKey": "158b08cc-6a06-49f2-a724-2bc514fdcf1e"
}

{% endtab %} {% endtabs %}

Create Signature

Below is the code example you can use to create the signature, which can then be compared with the one received in the event object to verify it was sent from Syskit Point.

private static string generateSignature(string content, string authKey)
{
    var keyBytes = Encoding.UTF8.GetBytes(authKey);
    var payloadBytes = Encoding.UTF8.GetBytes(content);

    using var hmac = new HMACSHA256(keyBytes);
    var hashBytes = hmac.ComputeHash(payloadBytes);
    return Convert.ToBase64String(hashBytes);
}

Webhooks

This article explains how to configure and use Syskit Point's webhooks.

Registering a Webhook Endpoint with Syskit Point API

Webhook Events

Signature Validation