Webhooks

When your OpenAPI document declares a top-level webhooks block, every generated SDK ships standalone, tree-shakable webhook verification helpers — no client instance required. A spec that declares no webhooks gets none of this surface, so an API with no event delivery does not carry verifier code it can never use. They take the raw request body, the signature header, and your signing secret, verify the signature in constant time, and return the parsed payload (or throw on a bad or missing signature). Use them in your webhook handler before trusting a delivery.

import { verifyHmacWebhook } from 'glotto-sdk';

const event = await verifyHmacWebhook('<raw-body>', '<signature>', '<secret>');
console.log(event);

HMAC signatures

verifyHmacWebhook (TypeScript) / verify_webhook (Python) / VerifyWebhook (Go) compute an HMAC-SHA256 of the raw payload with your secret and compare it to the provided signature using a timing-safe equality check. The signature encoding (hex or base64) is selectable. A mismatch raises WebhookVerificationError; a success returns the parsed body.

Standard Webhooks

For providers that follow the Standard Webhooks spec, the SDK also emits verifyStandardWebhook — it reads the webhook-id, webhook-timestamp, and webhook-signature headers, enforces a configurable timestamp tolerance (replay protection), and verifies the base64 signature. Stripe-style signatures are handled by a sibling helper where the spec advertises them.

Why a standalone helper

Verification is crypto over raw bytes, so it can’t go through the typed client — it runs in your HTTP handler before any parsing. The helpers depend only on Web Crypto (no Node built-ins), so the same function works in a server, an edge runtime, or a serverless handler.