# WorkOS webhook trigger

> Run a workflow on WorkOS Events API webhooks: User Management, Organizations, SSO connections, and Directory Sync, with signature verification.

Source: https://cotera.co/docs/reference/webhooks/workos

---

Run a workflow on WorkOS events — a user is created, an SSO connection is activated, a directory sync adds someone to a group. The event becomes the workflow's input, so you can provision access, sync your own systems, or alert on identity changes.

For behavior shared by every provider (the delivery URL, testing), see the [webhook triggers reference](https://cotera.co/docs/reference/webhooks.md).

## Prerequisites

WorkOS webhooks are **auto-registered**: Cotera creates the webhook endpoint for you over WorkOS's API. You supply a **WorkOS API Key** (`sk_live_...`) on the trigger's setup page (see WorkOS's [webhooks docs](https://workos.com/docs/reference/webhooks)). Without it, install fails with `workos_credentials_missing`.

## Setup

1. Add a **From an app** trigger and pick **WorkOS**, and enter your WorkOS API key.
2. Choose the event (see below).
3. Save. Cotera creates a WorkOS webhook endpoint enabled for that event, pointed at the trigger's unique URL.

Deleting the trigger removes the endpoint from WorkOS.

## Events

The event key is the WorkOS `event` string.

| Event key                         | Fires when                               |
| --------------------------------- | ---------------------------------------- |
| `user.created`                    | A user is created                        |
| `user.updated`                    | A user is updated                        |
| `user.deleted`                    | A user is deleted                        |
| `organization.created`            | An organization is created               |
| `organization.updated`            | An organization is updated               |
| `organization.deleted`            | An organization is deleted               |
| `organization_membership.created` | A user joins an organization             |
| `organization_membership.deleted` | A user leaves an organization            |
| `connection.activated`            | An SSO connection is activated           |
| `connection.deactivated`          | An SSO connection is deactivated         |
| `dsync.user.created`              | A directory sync user is created         |
| `dsync.user.deleted`              | A directory sync user is deleted         |
| `dsync.group.user_added`          | A user is added to a directory group     |
| `dsync.group.user_removed`        | A user is removed from a directory group |
| `session.created`                 | A user authentication session is created |

## Payload

The WorkOS event envelope is passed through as the workflow input; the affected resource is at `data`. A `user.created` delivery looks like:

```json
{
  "object": "event",
  "id": "evt_01EXAMPLE0000000000000000",
  "event": "user.created",
  "data": {
    "object": "user",
    "id": "user_01EXAMPLE0000000000000000",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "created_at": "2023-07-15T10:30:00.000Z"
}
```

| Field        | Description                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `id`         | The WorkOS event id, used to deduplicate retries.                                                                        |
| `event`      | The event type — matches the trigger's selected event.                                                                   |
| `data`       | The affected resource; `data.object` names its type (`user`, `organization`, `connection`, `directory_user`, and so on). |
| `created_at` | When the event happened.                                                                                                 |

## Signature verification

WorkOS signs each delivery with the `WorkOS-Signature` header in the form `t=<timestamp>, v1=<hex>` — an HMAC-SHA256, in hexadecimal, over `<timestamp>.<raw-body>`. The signing secret is generated by WorkOS when the endpoint is created, so there's no per-trigger secret for you to manage. Cotera verifies it on every delivery and rejects anything that fails.