Webhooks (Outbound)

When an event happens in your tenant, HummyTummy POSTs an HMAC-SHA256–signed HTTP request to your registered endpoint. This lets you react instantly to order, payment, and product/renewal events without polling.

All paths are under the /api global prefix.

Subscribe

Create a subscription. The secret is returned once — store it securely; it is never shown again and cannot be re-derived.

curl -X POST https://hummytummy.com/api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/hummytummy",
    "events": ["order.created.v1", "payment.succeeded.v1"]
  }'

const res = await fetch(
  "https://hummytummy.com/api/v1/webhooks/subscriptions",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${adminJwt}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/hummytummy",
      events: ["order.created.v1", "payment.succeeded.v1"],
    }),
  },
);
const { secret } = await res.json(); // returned ONCE — store securely

Request body:

Response (excerpt):

{
  "id": "0190a1b2-...",
  "tenantId": "...",
  "url": "https://hooks.example.com/hummytummy",
  "events": ["order.created.v1", "payment.succeeded.v1"],
  "status": "active",
  "secret": "whs_AbCdEf..."
}

List / revoke subscriptions:

GET    /api/v1/webhooks/subscriptions
DELETE /api/v1/webhooks/subscriptions/:id

Delivered payload

Each delivery is a POST with a JSON body:

{
  "id": "0190a1b2-c3d4-...",
  "type": "order.created.v1",
  "tenantId": "...",
  "payload": { "...event-specific fields..." }
}

Plus these headers:

Verifying the signature

The signature is a timestamped HMAC-SHA256 computed over the body:

X-HummyTummy-Signature: t=<unix-ms>,v1=<hmac-sha256-hex>

It is produced like this — the signed string is "<timestamp>.<rawBody>", and the key is your secret:

v1 = HMAC_SHA256(secret, `${t}.${rawBody}`)  // hex

Verification steps (identical to HummyTummy’s own verify logic):

Node.js (Express) verification example

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
 
const app = express();
 
// Capture the raw body — the signature is computed over the raw bytes.
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));
 
function verify(
  secret: string,
  header: string,
  rawBody: string,
  toleranceMs = 5 * 60_000,
): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  const v1 = String(parts.v1 ?? "");
  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > toleranceMs) return false;
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  if (expected.length !== v1.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
 
app.post("/hummytummy", (req, res) => {
  const sig = req.header("X-HummyTummy-Signature") ?? "";
  const raw = (req as any).rawBody.toString("utf8");
  if (!verify(process.env.WEBHOOK_SECRET!, sig, raw)) {
    return res.sendStatus(401); // invalid/stale signature
  }
  // Idempotency: don't process the same X-HummyTummy-Event-Id twice.
  const eventId = req.header("X-HummyTummy-Event-Id");
  // ... handle the event ...
  res.sendStatus(200); // 2xx = successful delivery
});

Event types

List specific types in the events field, or use "*" to catch all publishable events. Types follow the <area>.<action>.v<version> shape.

Example publishable types:

Blocked events

Some sensitive events are kept internal and are never sent out — not even a "*" subscription receives them. Blocking is by prefix; no event whose type starts with the following prefixes is delivered:

user.password
user.email_verification
auth.
subscription.upgrade.requested
subscription.renewal.failed
subscription.payment.
kms.
audit.

Retries and auto-pause

Delivery is performed by a worker that runs every 30 seconds.

• Timeout: a single delivery is capped at 15 seconds.
• Retry: on a non-2xx response or network error, up to 5 attempts with increasing backoff (30 s, 2 m, 10 m, 1 h, 6 h); after that the delivery is marked failed.
• Auto-pause: a subscription is automatically set to paused after 20 consecutive failures. This stops a dead endpoint from draining the worker; you must fix it and create a new subscription.
• Success resets the counter: a successful delivery resets the consecutive-failure counter to 0.

SSRF protection (allowlist)

Webhook URLs pass a safety gate both at subscribe time and immediately before each delivery. This prevents a tenant from self-fetching internal services or cloud metadata endpoints (e.g. 169.254.169.254).

What’s blocked:

• Non-public IPs: loopback, private/internal ranges, link-local, cloud-metadata addresses, and their IPv4-mapped IPv6 equivalents.
• Dangerous ports (Redis, Postgres, etc.).
• Userinfo in the URL (user:pass@host).
• Protocols other than http/https.

Best practices

• Always verify the signature and dedup on id.
• Return 2xx quickly; queue heavy work (stay under the 15 s timeout).
• Store the secret server-side, in an environment variable / secret vault.
• If you find a subscription paused, fix your endpoint and re-subscribe.
• Use an HTTPS endpoint where possible.