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.
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
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
Point WorkOS at your URL
Paste the endpoint URL into WorkOS: Dashboard → Webhooks.
- 3
Inspect what arrives
Each delivery appears live in the dashboard with method, headers, body, query parameters, and source IP.
- 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 header | workos-signature |
|---|---|
| Algorithm | HMAC-SHA256 |
| Verification in webhooks.cc | Supported: 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
Create a free endpoint on webhooks.cc (sign in with GitHub, Google, or email, or use a guest endpoint without an account), then configure it as your webhook URL: Dashboard → Webhooks. Every delivery shows up live in the dashboard with full headers, body, and query parameters. To hit a local server, run whk tunnel <port> and the CLI forwards each webhook to localhost.
Yes. webhooks.cc ships WorkOS templates (user.created, dsync.user.created, connection.activated) with realistic payloads and correctly computed signature headers. Send them from the dashboard, the SDK, or the MCP server to exercise your handler end-to-end.
WorkOS signs each delivery with the workos-signature header using HMAC-SHA256. webhooks.cc verifies these signatures for you: add your signing secret to the endpoint and every captured request is marked valid or invalid in the dashboard.
Yes. A free account gets you persistent endpoints, 50 requests per day, 7-day retention, and full CLI, SDK, and MCP access, with no credit card. You can also try a guest endpoint without an account: up to 25 requests for 12 hours.
More providers
Your WorkOS webhook URL is seconds away
Sign up free, create an endpoint, and point WorkOS at it.
No credit card · or try without an account