Skip to main content
The @team-plain/webhooks package provides typed webhook parsing and HMAC-SHA256 signature verification. It is a standalone package with no dependency on @team-plain/graphql.

​
Installation

npm install @team-plain/webhooks
verifyPlainWebhook validates the HMAC-SHA256 signature, checks the timestamp to prevent replay attacks, and parses the payload against the webhook JSON schema. 
import { verifyPlainWebhook } from "@team-plain/webhooks";

const result = verifyPlainWebhook(
  rawBody,                                  // raw request body string
  req.headers["plain-request-signature"],   // signature header
  process.env.PLAIN_WEBHOOK_SECRET,         // your webhook signing secret
);

if (result.error) {
  console.error(result.error.message);
} else {
  const event = result.data;
  console.log(event.eventType, event.payload);
}
The optional fourth argument tolerance (default: 300 seconds) controls the maximum allowed age of the webhook timestamp.

​
Parse only (no signature verification)

parsePlainWebhook validates the payload against the webhook JSON schema without checking the signature. Useful for development or when verification is handled elsewhere. 
import { parsePlainWebhook } from "@team-plain/webhooks";

const result = parsePlainWebhook(rawBody);

if (result.error) {
  console.error(result.error.message);
} else {
  const event = result.data;
  console.log(event.eventType, event.payload);
}

​
Error types

All functions return a Result<T, Error> — either { data: T } or { error: Error }.
Error classWhen
PlainWebhookSignatureVerificationErrorInvalid signature, missing headers, or expired timestamp
PlainWebhookPayloadErrorPayload fails JSON schema validation
PlainWebhookVersionMismatchErrorPayload version doesn’t match the schema version bundled in this package

​
Typed event payloads

All webhook payload types are exported for use in your handlers: 
import type {
  ThreadCreatedPublicEventPayload,
  CustomerCreatedPublicEventPayload,
  // ...
} from "@team-plain/webhooks";
See the full list of webhook events for all available event types.

​
Resources