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
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
- From the Home page, click Administration > Webhooks.
-
Click Add webhook.
-
In the General section, complete the fields:
-
(Optional) Move the Enabled slider to enable or disable the
webhook.
NOTE: When the webhook is disabled, the HTTP callback does not happen.
-
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.
-
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.
-
(Optional) Move the Enabled slider to enable or disable the
webhook.
-
In the Webhook details section, complete the fields:
-
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
NOTE: Your organization is responsible for providing the URL that you want the webhook event notifications forwarded to. -
(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.
-
Enter a valid HTTPS://
URL for your API (program or application).
-
(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.
-
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).
- Enter the header parameter Value.
-
(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).
- (Optional) Click , to remove any headers that are no longer required.
-
Enter the header parameter Name.
-
In the Event section, configure the settings you require:
- From the Event list, select an event that you want this webhook to listen for.
-
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:Code
{ "$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" ],
- Click Save.