Webhooks

Clarity allows you to set up custom webhooks in order to dynamically push data into Clarity, triggering any desired workflow trigger. A Clarity webhook is a customized API route which accepts a JSON payload and kicks off any one of our workflows.

Configuring the Webhook

To set up a new custom webhook, first head to Settings > Workflows and then click the "Webhooks" button in the top nav.

The webhooks page will show a list of all of your currently configured webhooks. To add a new webhook, click the Add New Webhook button and you will be presented with the form below:

To configure the webhook, fill out the form as necessary.

• Method: Select which HTTP request method you would like. The method you choose is up to you. Typically, a GET request or POST request is appropriate.

• Endpoint: Fill in the custom url route you would like to use. This is completely up to you, but the name should indicate what the webhook is intended to trigger. An example might be "github/commit-detected" or "service-now/provision-entitlement".

• Trigger: Pick any one of the available workflow triggers in Clarity. When the webhook receives a request, it will automatically kick off any workflows attached to this Trigger.

In the screenshot above, we are creating a new custom webhook which is expecting a POST request to the endpoint custom-provision-entitlement which will trigger the Provision Entitlement workflow.

Each workflow trigger in Clarity requires different context in order to run. For example, the Provision Entitlement trigger must be supplied information about which Entitlement you are trying to provision, which Identity you are trying to grant that entitlement to, and so forth. When you select the desired Trigger in the webhook configuration, all of the required context parameters are displayed. The PRovision Enttilement Trigger required the following context: app_identifier,identity_id,entitlement_id,expiration,grant_type,meta,creator_id.

Once you have configured the webhook appropriately, click Create Webhook button. After creating the webhook, you may close the form. Refresh the page to see your new webhook.

Clicking on the webhook in the list will take you to a detailed view of your new webhook (depicted below), including the required authentication token, method, url, and required context.

Sending a Request

Now all you need to do is send the appropriate request to your new custom webhook, and Clarity will handle the rest!

Below is a sample request using the Postman application to trigger our new webhook:

Authentication

Each webhook request must include an authorization header called x-clarity-webhook-token. This token is unique for each webhook you configure and should not be shared lightly!

Need help?