> ## Documentation Index
> Fetch the complete documentation index at: https://www.c1.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure webhooks

> Set up webhooks in C1 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 C1 to extend your access control workflows across multiple tools.

<Steps>
  <Step>
    Navigate to **Integrations** > **Webhooks**.
  </Step>

  <Step>
    Click **Add webhook**.
  </Step>

  <Step>
    Give the webhook a name and description so that you and your colleagues can easily identify its purpose.
  </Step>

  <Step>
    Enter the URL for the webhook.
  </Step>

  <Step>
    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.
  </Step>
</Steps>

### Test a webhook

Here's how to test a webhook once you've set it up in C1:

<Steps>
  <Step>
    On the **Webhooks** tab, click the more actions (**...**) menu and select **Test webhook**. The webhook fires with an empty payload.
  </Step>

  <Step>
    Click **View history** to see details of the webhook's payload and status.
  </Step>
</Steps>

## Webhook authentication

Webhooks include the `Authorization` header set with a bearer token that can be used to authenticate that the webhook came from C1. 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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "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 C1. 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:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "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](https://www.conductorone.com/docs/api-reference/task/get). |

## Configuring callback URL responses

When setting up callback URLs for use with C1, 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:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "version": "v1",
  "reassign": {
      "comment": "Reassigning to Alice Rodriguez",
      "newStepUserIds": ["2mqg9IILyNefQ6oMTvolM4FjDTS"]
  }
}
```

## Using a webhook to trigger a C1 automation

You can configure external systems to trigger C1 automations by sending authenticated HTTP requests to an inbound webhook endpoint. C1 supports both HMAC and JWT authentication methods.

For complete setup instructions, authentication details, code examples, and troubleshooting, see [Inbound webhooks](/product/admin/webhooks-inbound).

## Using webhooks for provisioning in C1

You configure an entitlement to use a webhook as its [provisioning strategy](/product/admin/access-requests#set-how-an-entitlement-is-provisioned), 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

<Tip>
  **Middleware for webhooks.**

  Configuring a webhook for use between C1 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.
</Tip>