Configure webhooks

Set up webhooks in ConductorOne to extend workflows across multiple tools, such as creating a ticket or making an API call.

Add a new webhook

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

Navigate to Admin > Settings and click the Webhooks tab.
Click Add webhook.
Give the webhook a name and description so that you and your colleagues can easily identify its purpose.
Enter the URL for the webhook.
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:

On the Webhooks tab, click the more actions (…) menu and select Test webhook. The webhook fires with an empty payload.
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
}

Claim	Description
`aud`	The domain that the webhook was delivered to.
`c1typ`	The type of token from ConductorOne. This will be ‘wh’ for webhooks.
`exp`	The expiration time.
`htb_s256`	The sha256 checksum of the request body for the webhook.
`htm`	The HTTP method that the webhook was delivered with.
`htu`	The target URL of the webhook.
`iat`	The time that the token was issued.
`iss`	The tenant domain that the token was issued for.
`jti`	The ID of the token
`nbf`	The earliest time the token should be accepted.

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:

Field	Description
`version`	The version of the webhook.
`webhookId`	The unique ID of the webhook.
`callbackUrl`	A URL that a delayed response can be sent to after responding with HTTP status code 202.
`event`	The type of the event the webhook was dispatched for (see below).
`payload`	The contextual payload of the webhook based on the type.

Payload types

Event type	Description
`c1.webhooks.v1.PayloadTest`	An empty payload.
`c1.webhooks.v1.PayloadProvisionStep`	The same payload that is returned from the GetTask API endpoint.

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.