Overview

Wocha sends HTTP POST requests to your endpoint when lifecycle events occur in your tenant. This guide covers the Customer API webhook delivery format — the same format implemented by @wocha/sdk/webhooks.

Register a webhook

In the Wocha Console or via the Customer API:

import { WochaClient } from "@wocha/sdk";
 
const wocha = new WochaClient({
  tenant: "my-tenant",
  apiKey: process.env.WOCHA_API_KEY!,
});
 
const webhook = await wocha.webhooks.create({
  url: "https://your-app.com/webhooks/wocha",
  events: ["user.created", "session.created"],
});
// Save webhook.secret — shown once at creation

Loading playground…

Verify signatures

Each delivery includes a signature header. Verify it with the webhook secret before processing:

import { verifyWebhookSignature } from "@wocha/sdk/webhooks";
 
const valid = verifyWebhookSignature({
  payload: rawBody,
  signature: request.headers.get("wocha-signature")!,
  secret: process.env.WOCHA_WEBHOOK_SECRET!,
});

Event envelope

Every delivery includes top-level envelope fields plus a typed data object:

{
  "event_type": "user.created",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-30T12:00:00.000Z",
  "idempotency_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "data": {}
}

Common events

Event	Description
`user.created`	New identity registered
`user.updated`	Traits or metadata changed
`user.deleted`	Identity removed
`session.created`	Session issued
`session.revoked`	Session terminated
`organisation.created`	Organisation created
`organisation.member_added`	User added to org
`organisation.member_removed`	User removed from org

Local development

Use the CLI to forward webhooks to localhost:

npx @wocha/cli webhooks listen --url http://localhost:3000/webhooks/wocha