Callbacks & signature verification

Callbacks aren’t live yet. This page documents the design so you can plan for it; nothing below is callable today. Until it ships, poll GET /v1/auth/test periodically to detect a disconnect (401 token_revoked) instead of waiting for app.uninstalled.

When callbacks ship, Workchats will POST signed events to your App’s registered callback URL — one URL per App, shared across every company that installs it.

Envelope

{
  "id": "evt_01J9ZK3…",
  "type": "directory.changed",
  "workspace_id": "cmp_…",
  "created_at": "2026-09-28T11:06:40Z",
  "data": { "kind": "user.deactivated", "id": "usr_9a1…" }
}

id is unique per event, so a retried delivery is safe to ignore if you’ve already processed that id.

Event types

Type	Fires when	`data`
`app.uninstalled`	A company admin uninstalls your App, or Octogle disables it. Not sent for `POST /oauth/revoke` — that’s a disconnect from your side, not an uninstall.	`{"removed_by": {"id": "usr_…"} \| null, "reason": "admin" \| "app_disabled"}`
`directory.changed`	A user or conversation your bot can see changes: `user.created`, `user.updated`, `user.deactivated`, `conversation.created`, `conversation.renamed`, `conversation.archived`, `conversation.deleted`, `app.removed_from_conversation`	`{"kind": "…", "id": "…"}` — re-read the user or conversation to get the new state
`interaction`	Someone clicks an action button on a message your bot sent (needs Phase 2’s clickable buttons — see Blocks)	`action_id`, `value`, `user {id, email?}`, `message {id, conversation_id, metadata}`

Signature verification

Every callback carries:

X-Workchats-Timestamp: 1790593600
X-Workchats-Signature: v1=<hex>

<hex> is HMAC-SHA256(signing_secret, "<timestamp>.<raw request body>"), hex-encoded. Verify against the raw request body — parsing to JSON and re-serializing before checking the signature will not match.

Node

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidWorkchatsSignature(rawBody, timestamp, signatureHeader, signingSecret) {
  const expected = createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return signatureHeader
    .split(",")
    .some((part) => {
      const hex = part.trim().replace(/^v1=/, "");
      return (
        hex.length === expected.length &&
        timingSafeEqual(Buffer.from(hex, "hex"), Buffer.from(expected, "hex"))
      );
    });
}

Reject anything where the signature doesn’t match, or where the timestamp is more than 5 minutes old. During a signing-secret rotation, Workchats sends two comma-separated values — v1=<new>,v1=<old> — for 24 hours, so check every value in the header rather than only the first.

Delivery and retries

HTTPS only, TLS 1.2+, no redirects followed. A response other than 2xx within 3 seconds counts as a failure and is retried at 1 minute, 5 minutes, and 30 minutes, with the same event id. Respond 2xx as soon as you’ve durably queued the event — don’t do slow work in the request path before responding.

Getting Started

Guides

Reference

Changelog

Policies

Envelope

Event types

Signature verification

Delivery and retries

​Envelope

​Event types

​Signature verification

​Delivery and retries

Envelope

Event types

Signature verification

Delivery and retries