Get the Guide to Modern IGA

ConductorOne Docs

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.

  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
}
ClaimDescription
audThe domain that the webhook was delivered to.
c1typThe type of token from ConductorOne. This will be ‘wh’ for webhooks.
expThe expiration time.
htb_s256The sha256 checksum of the request body for the webhook.
htmThe HTTP method that the webhook was delivered with.
htuThe target URL of the webhook.
iatThe time that the token was issued.
issThe tenant domain that the token was issued for.
jtiThe ID of the token
nbfThe 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:

FieldDescription
versionThe version of the webhook.
webhookIdThe unique ID of the webhook.
callbackUrlA URL that a delayed response can be sent to after responding with HTTP status code 202.
eventThe type of the event the webhook was dispatched for (see below).
payloadThe contextual payload of the webhook based on the type.

Payload types

Event typeDescription
c1.webhooks.v1.PayloadTestAn empty payload.
c1.webhooks.v1.PayloadProvisionStepThe same payload that is returned from the GetTask API endpoint.

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.