> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks SDK

> Webhook parsing and signature verification for Plain webhooks.

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

```bash theme={null}
npm install @team-plain/webhooks
```

## Verify and parse (recommended)

`verifyPlainWebhook` validates the HMAC-SHA256 signature, checks the timestamp to prevent replay attacks, and parses the payload against the webhook JSON schema.

```ts theme={null}
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.

```ts theme={null}
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 class                              | When                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| `PlainWebhookSignatureVerificationError` | Invalid signature, missing headers, or expired timestamp                 |
| `PlainWebhookPayloadError`               | Payload fails JSON schema validation                                     |
| `PlainWebhookVersionMismatchError`       | Payload 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:

```ts theme={null}
import type {
  ThreadCreatedPublicEventPayload,
  CustomerCreatedPublicEventPayload,
  // ...
} from "@team-plain/webhooks";
```

See the full list of [webhook events](/webhooks/thread-created) for all available event types.

## Resources

* [Webhooks overview](/webhooks) — setup, security, delivery semantics, and retry policy
* [Request signing](/request-signing) — how Plain signs webhook requests
* [GitHub repository](https://github.com/team-plain/sdk/tree/main/packages/webhooks)