Add a new webhook

Set up a webhook in ConductorOne to extend your access control workflows across multiple tools.

1. Navigate to Admin > Settings and click the Webhooks tab.

2. Click Add webhook.

3. Give the webhook a name and description so that you and your colleagues can easily identify its purpose.

4. Enter the URL for the webhook.

5. Click Save. The new webhook is set up and assigned an ID. Click View history to see the webhook’s activity in the past eight days.

Test a webhook

Here’s how to test a webhook once you’ve set it up in ConductorOne:

1. On the Webhooks tab, click the more actions (…) menu and select Test webhook. The webhook fires with an empty payload.

2. Click View history to see details of the webhook’s payload and status.

Webhook authentication

Webhooks include the Authorization header set with a bearer token that can be used to authenticate that the webhook came from ConductorOne. This bearer token is a JWT that can be authenticated using the JWKS available at https://<YOUR DOMAIN>.conductor.one/auth/v1/jwks. After the token is authenticated, you can validate the request body using the htb_s256 claim included in the token.

The payload of the JWT looks like this:

{
  "aud": "webhook.site",
  "c1typ": "wh",
  "exp": 1713312240,
  "htb_s256": "VZ9Lx6npbJ2wf2oS4gqSlWPBlrOR6egghxnOMk9UKIM=",
  "htm": "POST",
  "htu": "https://webhook.site/729638b0-d919-4c7d-b14b-24dd68c84f22",
  "iat": 1713312120,
  "iss": "example.conductor.one",
  "jti": "2fCjnQxpBRyaQQgPO3rW6EWNdld",
  "nbf": 1713312060
}

Webhook payload

The contents of a webhook request vary based on the context of the webhook that is delivered. Each request includes a set of common fields that act as webhook metadata. Additionally, a payload is defined based on the event type of the webhook.

The most basic request is a test webhook, and it looks like this:

{
  "version": "v1",
  "webhookId": "2fCjgK8tYJxV9u8d1wupBMeXZ45",
  "callbackUrl": "https://test-domain.conductor.one/api/v1/webhooks/callback/ChsyNVR0dHZXSWhpQVYwT0N5ZWwwQTJiTVdGN1ISfXKaBFUxiS0r42OpH-ppdtxyUjkn1ExnOotjVEgk4p2bouIM8oSOvhcVDSEJLtIqhzTetQ-ckH3JbnS6k0nHefQhVTeZmmmW2KpIMUiaJooDgQ4Yyti5dTNduxNmI7kjlNff5XXZU1aw4QSv3vdKe0dD4KKjP5PGwL1x9nN9",
  "event": "c1.webhooks.v1.PayloadTest",
  "payload": {
    "@type": "type.googleapis.com/c1.webhooks.v1.PayloadTest"
  }
}

Here’s an explanation of the fields in the test webhook:

Payload types

Configuring callback URL responses

When setting up callback URLs for use with ConductorOne, remember:

• The POST to the callback URL must respond with HTTP status code 202.

• You don’t need to include session tokens. A blank POST call to the callback URL is enough.

Callback URLs for request policies

When configuring a callback URL to respond to a request policy, here’s what to include in the webhook body:

To approve a request and add a comment: {"version": "v1", "approve": {"comment": "This is approved."}}

To deny a request and add a comment: {"version": "v1", "deny": {"comment": "This is denied. Please reach out to IT."}}

To reassign a request and add a comment:

{
  "version": "v1",
  "reassign": {
      "comment": "Reassigning to Alice Rodriguez",
      "newStepUserIds": ["2mqg9IILyNefQ6oMTvolM4FjDTS"]
  }
}

Using webhooks in ConductorOne

Once you’ve set up a webhook, you can use it in a variety of ways.

Additional webhook functionality coming soon. We’re launching webhooks with support for provisioning access. Stay tuned: more ways to use webhooks in ConductorOne will be added soon.

Provisioning

You configure an entitlement to use a webhook as its provisioning strategy, meaning that when access to the entitlement is approved, the webhook will automatically fire. The webhook can perform a wide variety of work to automate the provisioning process, such as:

• Automatically creating a Jira, ServiceNow, or other service desk ticket

• Making a public API call to a tool your organization uses

• Calling the internal API of a backoffice, homegrown, or airgapped tool

• Sending a notification to a collaboration platform, such as pinging a Slack channel

• Adding an entry to an audit log

Middleware for webhooks. Configuring a webhook for use between ConductorOne and another tool often requires the creation of some middleware code. Integration Platform as a Service (iPaaS) tools such as Celigo, MuleSoft, or Zapier can help you to create this code.