Skip to content

Test WorkOS webhooks

WorkOS sends webhooks for authentication, user, session, organization, SSO connection, directory sync, and invitation events. Capture them on a free webhooks.cc endpoint to see exactly what WorkOS sends, or fire realistic, correctly signed sample payloads at your own handler without touching a production account.

Start free:
or sign up with email

No credit card · 50 requests/day free · or get a guest URL without an account

Prefer a walkthrough? Read the local webhook testing guide.

How to test WorkOS webhooks

  1. 1

    Create a webhook endpoint

    Sign in free with GitHub, Google, or email to create a persistent endpoint, or grab an instant guest URL at webhooks.cc without an account.

  2. 2

    Point WorkOS at your URL

    Paste the endpoint URL into WorkOS: Dashboard → Webhooks.

  3. 3

    Inspect what arrives

    Each delivery appears live in the dashboard with method, headers, body, query parameters, and source IP.

  4. 4

    Forward to localhost or assert in CI

    Run whk tunnel <port> to forward webhooks to a local server, or use the TypeScript, Python or Go SDK to wait for and assert on deliveries in tests.

WorkOS webhook signature

Signature headerworkos-signature
AlgorithmHMAC-SHA256
Verification in webhooks.ccSupported: add your signing secret and every request is checked automatically

Checking one request by hand? Paste its body and headers into the webhook signature checker, which has the WorkOS scheme built in and runs in your browser.

New to signature verification? Read the webhook signature verification guide.

Send sample WorkOS events

These WorkOS templates ship with realistic payloads and valid signature headers. Send them from the dashboard's Send button, the SDK, or your AI agent via MCP.

user.createddsync.user.createdconnection.activatedsession.createdorganization.created
# Send a signed WorkOS sample with the SDK
await client.endpoints.sendTemplate( slug, {
  provider: "workos",
  template: "user.created",
  secret: "your-test-secret",
});

Test your WorkOS webhook handler in CI

sendTo signs each request the way WorkOS does, with your test secret from WORKOS_WEBHOOK_SECRET, and posts it straight to your handler, so its signature check stays on. The second test proves the handler rejects a forged signature. Drop the file into a Vitest suite that runs against your app; for Jest, delete the first line, since Jest provides the same globals.

import { describe, expect, it } from "vitest";
import { WebhooksCC } from "@webhooks-cc/sdk";

// Runs against your app on localhost. WHK_API_KEY and WORKOS_WEBHOOK_SECRET come from the env.
const client = new WebhooksCC({ apiKey: process.env.WHK_API_KEY! });
const url = "http://localhost:3000/api/webhooks/workos";

const send = (secret: string) =>
  client.sendTo(url, {
    provider: "workos",
    template: "user.created",
    secret,
  });

describe("WorkOS webhook handler", () => {
  it("accepts a signed user.created", async () => {
    const response = await send(process.env.WORKOS_WEBHOOK_SECRET!);
    expect(response.status).toBeGreaterThanOrEqual(200);
    expect(response.status).toBeLessThan(300);
  });

  it("rejects a forged signature", async () => {
    const response = await send("not-the-real-secret");
    // A 4xx, not a crash: providers retry 5xx responses.
    expect(response.status).toBeGreaterThanOrEqual(400);
    expect(response.status).toBeLessThan(500);
  });
});

Let your coding agent write and run it: the webhooks.cc agent skill teaches Claude Code, Cursor, and Codex to test webhook handlers with signed payloads. More patterns in the SDK testing docs.

Everything in one place

  • Live dashboard: see deliveries the moment they arrive
  • Forward to localhost with whk tunnel
  • Replay any captured request to any URL
  • Mock responses with custom status, headers, and body
  • Forward to your servers, Slack or Discord
  • TypeScript, Python and Go SDKs for CI assertions
  • MCP server for AI coding agents

WorkOS webhook questions

More providers

Browse all 68 providers

Your WorkOS webhook URL is seconds away

Sign up free, create an endpoint, and point WorkOS at it.

or sign up with email

No credit card · or try without an account