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

# Webhook Keys

> Webhook keys are HMAC signing secrets used to verify that webhook payloads come from Connectly. One active key per business at a time 🔑

Webhook keys are separate from webhook registrations. A webhook registration defines *where* Connectly sends events. A webhook key is the **HMAC signing secret** used to verify that those events actually came from Connectly — it's included in every request as the `x-connectly-hmac-sha256` header.

<Note>
  There is only ever **one active webhook key per business** at a time. Creating a new key automatically revokes the previous one. Old revoked keys are retained in the system (soft-deleted) but are no longer valid — this is why you may see multiple keys listed when you call the list endpoint.
</Note>

***

## Endpoints

| Method | Endpoint                                                   | Description                                                                                                   |
| ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/businesses/{businessId}/business_keys`                | List all keys — shows type, status (`active`/`expired`/`revoked`), masked key value, and creation timestamps. |
| `POST` | `/v1/businesses/{businessId}/business_keys`                | Create a new webhook signing key. Automatically revokes the currently active key.                             |
| `POST` | `/v1/businesses/{businessId}/business_keys/{keyId}/revoke` | Revoke a specific key by ID.                                                                                  |

***

## List your keys

Use this to see the status of all keys associated with your business — useful if you're seeing unexpected keys in your account:

```bash theme={null}
curl -X GET "https://api.connectly.ai/v1/businesses/{businessId}/business_keys" \
  -H "X-API-Key: YOUR_API_KEY"
```

The response shows each key's `status` (`active`, `expired`, or `revoked`) and `created_at` timestamp. Only one key will have `status: active` — the rest are historical rotations.

***

## Rotate your key

Creating a new key immediately revokes the current active one:

```bash theme={null}
curl -X POST "https://api.connectly.ai/v1/businesses/{businessId}/business_keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

<Warning>
  After rotating, update your webhook handler with the new secret immediately — any requests verified against the old key will fail.
</Warning>

***

## Verify webhook payloads

Use the active key to verify the `x-connectly-hmac-sha256` header on every incoming webhook request. See [Webhooks overview](/webhooks/overview#verify-hmac-signatures) for the verification code example.