For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Apply for AccessDashboard
Guides
Guides
  • Get Started
    • Introduction
    • Quickstart
  • Agent Identity
    • Overview
    • Create Auth Intent
    • Exchange for JWT
    • Sessions
    • JWKS
  • Agent Checkout
    • Overview
    • Create an Invoice
    • List Invoices
    • Get Invoice
    • Cancel Invoice
  • Integration Patterns
    • Overview
    • Shared SDK Client
    • Wallet Auth
    • JWT Verification
    • Subscription Checkout
    • Webhook Verification
  • Concepts
    • Two Invoice IDs
    • Wallet Identity
    • Session vs Token
    • Webhook-Driven State
  • Webhooks
    • Overview
    • Verify Signatures
  • Reliability
    • Errors
    • SDK Reference
Apply for AccessDashboard
On this page
  • Why this pattern
  • Recommended shape
  • Related pages
Integration Patterns

Webhook Verification

Validate raw signed deliveries before updating local state
||View as Markdown|
Was this page helpful?
Edit this page
Previous

Subscription Checkout

Next

Two Invoice IDs

Built with

Webhook handling should be intentionally strict: verify first, then trust the payload.

Why this pattern

  • the SDK checks HMAC signature and timestamp freshness
  • the app preserves the exact raw request body for verification
  • downstream handlers switch on a typed eventType
  • local state changes happen only after signature validation succeeds

Recommended shape

1import { readFile } from "node:fs/promises";
2
3const rawBody = await readFile(rawBodyPath, "utf8");
4const webhookUrl =
5 `${config.publicBaseUrl ?? `http://127.0.0.1:${config.port}`}` +
6 "/v1/webhooks/gwop";
7
8const event = await webhooks.validateWebhook({
9 rawBody,
10 headers: {
11 "x-gwop-signature": signature,
12 "x-gwop-event-id": eventId,
13 "x-gwop-event-type": eventType,
14 },
15 url: webhookUrl,
16 method: "POST",
17});
18
19console.log(event.body.eventType);
20console.log(event.body.data.invoiceId);
21console.log(event.body.data.publicInvoiceId);

Do not parse and re-stringify the JSON before verification. The signature is computed over the original raw request body bytes.

Related pages

Verify Signatures

See the operational webhook verification flow and the manual fallback

Webhook-Driven State

Learn why signed delivery is the durable trigger for fulfillment

Webhooks

Review the event types and payload fields your handler should expect