> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# SSO connection events

Webhook events Scalekit sends when an organization's SSO connection is created, enabled, disabled or deleted, with sample payloads and fields.
Scalekit sends a webhook when an organization's SSO connection is created, enabled, disabled or deleted. Use these events to keep your app's record of which organizations can sign in with SSO in step with Scalekit, for example to show or hide an SSO button or to require SSO for an organization's users.

To receive them, add an endpoint in **Developers** > **Webhooks** and select the events. See [Implement webhooks](/authenticate/sso/webhooks/), and verify every delivery as described in [Verify webhook signatures](/guides/webhooks-best-practices/#verify-webhook-signatures).

| Event | Sent when |
|-------|-----------|
| [`organization.sso_created`](#organizationsso_created) | An SSO connection is created for an organization |
| [`organization.sso_enabled`](#organizationsso_enabled) | An SSO connection is enabled, so the organization's users can sign in with it |
| [`organization.sso_disabled`](#organizationsso_disabled) | An SSO connection is disabled, so its users can no longer sign in with it |
| [`organization.sso_deleted`](#organizationsso_deleted) | An SSO connection is deleted |

Scalekit doesn't send a webhook when a connection's configuration changes, such as its IdP metadata, certificate or attribute mapping. To read a connection's current configuration, call [Get connection details](/apis/#tag/connections). For how IdP certificate rotation works, see [Certificate expiry and rotation](/sso/guides/security-and-compliance/#certificate-expiry-and-rotation).

## Event envelope

Every SSO connection event has the same top-level fields. The connection is in `data`. Keys can arrive in any order, so parse the body as JSON rather than matching it as text.

| Field | Type | Description |
|-------|------|-------------|
| `spec_version` | string | Webhook payload version. Currently `"1"` |
| `id` | string | Unique event ID, prefixed with `evt_`. Use it to ignore duplicate deliveries |
| `type` | string | Event type, such as `organization.sso_enabled` |
| `occurred_at` | string | When the event occurred, in RFC 3339 format |
| `environment_id` | string | Environment the event belongs to |
| `organization_id` | string | Organization the connection belongs to |
| `object` | string | Always `Connection` |
| `data` | object | The connection. All four events carry the same fields |

### Connection fields in `data`

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Connection ID, prefixed with `conn_`. It's the `connection_id` you pass in an authorization URL |
| `organization_id` | string | Organization that owns the connection |
| `connection_type` | string | `SAML` or `OIDC` |
| `provider` | string | Identity provider, such as `OKTA` or `MICROSOFT_AD` |
| `enabled` | boolean or null | Whether users can sign in with the connection. `null` when the value wasn't recorded with the event |
| `status` | string or null | Setup progress: `DRAFT`, `IN_PROGRESS` or `COMPLETED`. `null` when the value wasn't recorded with the event |

## `organization.sso_created`

Sent when an SSO connection is created for an organization, from the dashboard, the admin portal or the API. A new connection is usually disabled and in `DRAFT` until your customer's IT admin finishes setup and enables it.

```json title="organization.sso_created"
{
  "spec_version": "1",
  "id": "evt_94567862441607493",
  "type": "organization.sso_created",
  "occurred_at": "2025-10-14T09:27:18.488720586Z",
  "environment_id": "env_74418471961625391",
  "organization_id": "org_83544995172188677",
  "object": "Connection",
  "data": {
    "id": "conn_94567862424830277",
    "organization_id": "org_83544995172188677",
    "connection_type": "OIDC",
    "provider": "OKTA",
    "enabled": false,
    "status": "DRAFT"
  }
}
```

## `organization.sso_enabled`

Sent when an SSO connection is enabled. From now on, the organization's users can sign in through it.

```json title="organization.sso_enabled"
{
  "spec_version": "1",
  "id": "evt_94568078213382471",
  "type": "organization.sso_enabled",
  "occurred_at": "2025-10-14T09:29:27.098914861Z",
  "environment_id": "env_74418471961625391",
  "organization_id": "org_83544995172188677",
  "object": "Connection",
  "data": {
    "id": "conn_94567862424830277",
    "organization_id": "org_83544995172188677",
    "connection_type": "OIDC",
    "provider": "OKTA",
    "enabled": true,
    "status": "COMPLETED"
  }
}
```

## `organization.sso_disabled`

Sent when an SSO connection is disabled. Sign-in requests that target this connection now fail with `connection_not_active` or `no_active_connections` (see the [error reference](/sso/reference/sso-integration-errors/)), so route the organization's users to another sign-in method until it's enabled again.

```json title="organization.sso_disabled"
{
  "spec_version": "1",
  "id": "evt_94557976165089560",
  "type": "organization.sso_disabled",
  "occurred_at": "2025-10-14T07:49:05.809554456Z",
  "environment_id": "env_74418471961625391",
  "organization_id": "org_83544995172188677",
  "object": "Connection",
  "data": {
    "id": "conn_83545002856153607",
    "organization_id": "org_83544995172188677",
    "connection_type": "OIDC",
    "provider": "OKTA",
    "enabled": false,
    "status": "COMPLETED"
  }
}
```

## `organization.sso_deleted`

Sent when an SSO connection is deleted. If your customer creates a new connection, it has a new connection ID, so the `sub` of their users changes. See [Choose a stable user identifier](/sso/guides/user-profile-details/#choose-a-stable-user-identifier).

```json title="organization.sso_deleted"
{
  "spec_version": "1",
  "id": "evt_94557997639926040",
  "type": "organization.sso_deleted",
  "occurred_at": "2025-10-14T07:49:18.604546332Z",
  "environment_id": "env_74418471961625391",
  "organization_id": "org_83544995172188677",
  "object": "Connection",
  "data": {
    "id": "conn_83545002856153607",
    "organization_id": "org_83544995172188677",
    "connection_type": "OIDC",
    "provider": "OKTA",
    "enabled": false,
    "status": "COMPLETED"
  }
}
```


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |