Creating webhooks

2022-08-22Last updated

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.

Before you begin

Learn about webhooks.

What you should know

  • Only an account administrator can create webhooks in ClearID.
  • External organizations are responsible for developing their own third-party solution APIs (programs or applications) that consume ClearID webhook HTTP callback notifications.

Procedure

  1. From the Home page, click Administration > Webhooks .
  2. Click Add webhook.
    Webhook details page in ClearID showing Webhook details section, Additional headers section, and Event section.
  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.
    Additional headers section of the Webhooks details page in ClearID with an invalid header message highlighted.
    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).
      Additional headers section of the Webhook details page in ClearID showing an example additional header Name and Value.
    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.
Your webhook is now configured to integrate with a third-party API (program or application) to notify interested parties when specific events occur.

After you finish

Using the downloaded schema, configure your third-party API to receive and process the webhook notifications.