Creating webhooks

You can create webhooks in Genetec ClearID™ to integrate with third-party solutions APIs so that you can notify interested parties when specific events occur.

1. From the Home page, click Administration > Webhooks .
2. Click Add webhook.

   

3. In the General section, complete the fields:
   1. (Optional) Move the Enabled slider to enable or disable the webhook.
      Note: When the webhook is disabled, the HTTP callback does not happen.
   2. In the Name field, enter a meaningful Name so that you can easily identify your webhook later on.
      For example, Identity updated or Identity requests created webhook and so on.
   3. In the Description field, enter a Description that describes the purpose of the webhook.
      For example, what the webhook is for, and what API (program or application) it notifies when events occur.
4. In the Webhook details section, complete the fields:
   1. Enter a valid HTTPS:// URL for your API (program or application).
      URLs can include ports and query parameters as follows:

      • Example 1: https://my-api.com/identityupdatedendpoint
      • Example 2: https://my-api.com:8080/identity-updated-endpoint?my-query-param=123

      This URL is used to forward the webhook event notification to the relevant third-party API (program or application).

      Note: Your organization is responsible for providing the URL that you want the webhook event notifications forwarded to.
   2. (Optional) Enter the Secret (App key) if required by the third-party API.
      The secret (App key) is used to authenticate communications between the ClearID webhook and your organizations third-party API.
5. (Optional) In the Additional headers section, complete the fields:
   Extra custom HTTP headers can be added in the HTTP callback request so that they can be used by the third-party API on the user's side of the integration.

   Note: If you enter an invalid or reserved header, the following message is displayed The submitted HTTP request header is invalid or misused.

   

   1. Enter the header parameter Name.
      For example, if you had one event coming from multiple sources, extra HTTP request headers could be used to specify where event is coming from (ClearID or external API).

      

   2. Enter the header parameter Value.
   3. (Optional) Click Add header to add extra HTTP request headers as required.
      For example, if your API is expecting or requires a specific set of headers (Host, Origin, Language, and so on).
   4. (Optional) Click , to remove any headers that are no longer required.
6. In the Event section, configure the settings you require:
   1. From the Event list, select an event that you want this webhook to listen for.
   2. Click Download schema and follow your browser prompts.
      Best Practice: Use the downloaded schema information to understand the data structure of the events so that they can be retrieved and processed correctly on the user's side of the integration.

      The following example shows an extract from a schema-identitycreated.json file:

      {
        "$schema": "http://json-schema.org/draft-04/schema#",
        "title": "IdentityDeletedCallbackModel",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "AccountId",
          "IdentityId",
          "DeletedBy",
          "DeletionDateUtc"
        ],
        "properties": {
          "AccountId": {
            "type": "string",
            "description": "The account id for which this identity is member of.",
            "minLength": 1
          },
          "IdentityId": {
            "type": "string",
            "description": "A unique id to identify the identity.",
            "minLength": 1
          },
          "ExternalId": {
            "type": [
              "null",
              "string"
            ],
            "description": "External ID"
          },
          "Ordinal": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Commit ordinal in the storage.",
            "format": "int64"
          },
          "Email": {
            "type": [
              "null",
              "string"
            ],

7. Click Save.