Reliable webhooks for signing workflows

Authenticate the raw request before trusting its fields

A webhook endpoint is public by design. Verify its HMAC signature against the exact raw request body before parsing or acting on the event. If a proxy or framework rewrites the body first, the computed digest can change.

Use a high-entropy secret, compare signatures in constant time, require HTTPS, and rotate secrets through a controlled deployment process. GitHub’s webhook guidance follows the same core pattern: protect deliveries with a secret and do not let intermediaries modify the signed payload.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", webhookSecret)
  .update(rawBody)
  .digest("hex");

const trusted = timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(signature),
);

Acknowledge quickly, then do durable work

Validate the request, persist the delivery identifier and payload, enqueue the business operation, and return a successful response. Downloading completed PDFs, updating a CRM, or sending another email should happen outside the request path.

Fast acknowledgement reduces duplicate deliveries and prevents a temporary downstream slowdown from looking like a webhook failure.

Assume every event can arrive more than once

At-least-once delivery means duplicates are normal. Put a unique constraint on the provider delivery identifier or the pair of event type and event identifier. If the same event arrives again, return success without repeating side effects.

Business operations should also be idempotent. An event record can be unique while a downstream job is retried after partially completing.

• Store received, verified, queued, processed, and failed timestamps.
• Keep a bounded retry count with backoff and a dead-letter state.
• Expose the last response and error without logging secrets.
• Support deliberate redelivery after the underlying issue is fixed.

Use webhooks for speed and the API for reconciliation

A webhook should move your workflow forward quickly, but it should not be your only source of truth. Periodically reconcile important submissions against the Signa API so a prolonged outage or configuration error cannot leave records permanently stale.