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.

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). Without it, install fails with workos_credentials_missing.

Setup

Add a From an app trigger and pick WorkOS, and enter your WorkOS API key.
Choose the event (see below).
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:

{
  "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.