Webhook handler

Webhook handlers receive server-to-server event deliveries from Getme. A reliable handler verifies the signature, records idempotency keys, responds quickly, and does slow work asynchronously.

1. Create an endpoint

Create a webhook endpoint in the developer portal and subscribe only to the events your integration needs. Keep separate endpoints or routing rules for test and live traffic.

2. Verify the signature

Every delivery includes X-Getme-Signature. Verify it before trusting the payload.

import { constructEvent } from '@getme-tech/getme-node/webhooks';

const event = constructEvent(
  rawBody,
  request.headers['x-getme-signature'],
  process.env.GETME_WEBHOOK_SECRET,
);

Use the raw request body for verification. Parsing and re-serializing JSON before verification can change the signed bytes.

3. Make processing idempotent

Getme can deliver the same event more than once after network errors, endpoint timeouts, or manual retries. Store the event id or X-Getme-Delivery value and skip work you have already completed.

if (await alreadyProcessed(event.id)) {
  return new Response('ok', { status: 200 });
}

4. Respond quickly

Return a 2xx response after the event is accepted for processing. Queue slow tasks, such as fulfillment calls or email delivery, outside the request path.

5. Use payload contracts

The generated event catalog documents event names, payload fields, signing, and retry behavior. Treat the event catalog as the source of truth for webhook payload shape.