Receive & verify webhooks

GoFundNode POSTs state changes to your configured URL. Each delivery is HMAC-signed and at-least-once.

The envelope

Every webhook shares the envelope { event, eventId, occurredAt, data }. The data object is event-specific — it is not the GET /v1/submissions/:id response.

{
  "event":      "submission.completed",
  "eventId":    "evt_84621",
  "occurredAt": "2026-05-22T18:01:41Z",
  "data": {
    "submissionId":    "9a1f…",
    "status":          "submitted",
    "outcome":         "success",
    "failureReason":   null,
    "ledger":          { "node_seconds": 92, "actions": 26, "…": "…" },
    "actualCredits":   111.6,
    "refundedCredits": 142.6
  }
}

Event types

Headers on every webhook POST

Verify with the SDK (Fastify)

import Fastify from "fastify";
import { verifyWebhook, type WebhookEvent } from "@gofundnode/vendor-client";

const app = Fastify();

// Capture the raw body string for HMAC verification.
app.addContentTypeParser("application/json", { parseAs: "string" }, (req, body, done) => {
  (req as any).rawBody = body;
  try { done(null, body.length ? JSON.parse(body) : {}); }
  catch (e) { done(e as Error, undefined); }
});

app.post("/api/gfn/webhook", async (req, reply) => {
  const verified = verifyWebhook({
    rawBody: (req as any).rawBody,
    headers: {
      timestamp: req.headers["x-gfn-timestamp"],
      signature: req.headers["x-gfn-signature"],
    },
    webhookSecret: process.env.GFN_WEBHOOK_SECRET!,
  });
  if (!verified.ok) return reply.code(401).send({ error: verified.reason });

  const event = req.body as WebhookEvent;       // { event, eventId, occurredAt, data }
  const deliveryId = req.headers["x-gfn-delivery"];

  // Dedupe on X-GFN-Delivery BEFORE any side effect (at-least-once delivery).
  if (await alreadyHandled(deliveryId)) return reply.send({ received: true });

  switch (event.event) {                        // narrows event.data by type
    case "submission.completed":
    case "submission.failed":
    case "submission.cancelled":
      await onSettled(event.data);              // { submissionId, outcome, actualCredits, … }
      break;
    case "credits.low_balance":
      await onLowBalance(event.data);           // { balance, threshold }
      break;
    case "purchase.completed":
      await onPurchase(event.data);             // { reference, credits, … }
      break;
    default:
      break;                                    // frozen-additive: ignore unknown types
  }

  await markHandled(deliveryId);
  return reply.send({ received: true });        // reply 2xx fast
});

Express: use express.raw({ type: "application/json" }) on the webhook route and call verifyWebhook with req.body.toString("utf8"). Runnable: examples/webhook-handler.ts.

Retry policy

A 2xx ends the retry chain. 4xx (except 408/429) marks the delivery permanently failed. 5xx / network / 408 / 429 retry with exponential backoff up to GFN_WEBHOOK_MAX_RETRIES (default 8) attempts over ~8 hours: 30s, 1m, 5m, 15m, 45m, 2h, 4h, 8h. Per-attempt timeout defaults to 10s.

• Verify the signature before parsing/acting; reject with 401 on failure.
• Respond 2xx to acknowledge; any non-2xx triggers a retry.
• Dedupe on X-GFN-Delivery — the same event can arrive more than once.
• Finish within the per-attempt timeout (do heavy work async).