Index of every page on this site: llms.txt
Skip to content

Receive and verify gscdump webhooks

Use a partner server endpoint for webhook delivery. Verify the signature before acting on an event.

Before you start

Configure the signing secret for your webhook endpoint. Your endpoint verifies and processes each delivery. The hosted HTTP contract defines the installed event schema.

Read the raw request body

Read request.text() before JSON parsing. Verification uses the exact signed bytes. Do not reconstruct JSON or change whitespace first.

Verify the signature

import { parseWebhookPayload, WEBHOOK_SIGNATURE_HEADER } from '@gscdump/sdk/webhook'

export async function handleWebhook(request: Request, secret: string) {
  const raw = await request.text()
  const envelope = await parseWebhookPayload(raw, {
    secret,
    signature: request.headers.get(WEBHOOK_SIGNATURE_HEADER),
  })
  return envelope
}

parseWebhookPayload verifies the signature and parses the contract envelope. An invalid signature rejects the request. If you need separate steps, use verifyWebhookSignature on the raw body first.

Read a typed event

The parsed envelope is discriminated on event. Narrow on event before you read data:

if (envelope.event === 'user.allowance.notice') {
  const { userId, meter, threshold, used, allowance, period } = envelope.data
  await sendAllowanceNotice({ userId, meter, threshold, used, allowance, period })
}

gscdump sends user.allowance.notice only to a metered partner, at 80% and 100% of a free allowance. gscdump sends no email to that partner's users, so the partner sends its own notice. parseWebhookPayload rejects a notice whose data does not match the contract.

Process repeats and failures

Use envelope.deliveryId to deduplicate work. Make writes idempotent. Return success after durable processing or a durable queue accepts the work. A repeated delivery must not repeat a side effect.

Check delivery

Test with a signed payload from your installed contract or a real test delivery. Check valid signature, changed body, missing signature, duplicate delivery, and handler failure. Log the delivery ID, never the signing secret. See Errors and retry for the hosted HTTP path.