Plumtier Docs Deploy free

Webhooks

Signed events sent to your own server when orders, refunds, subscriptions and waitlists change.

Note
Webhooks are part of Plumtier Pro and Team.

Add an endpoint in Settings → Webhooks: an https:// address on your server and the events it wants. Plumtier creates a signing secret for it; copy it from the same screen.

Events

EventSent when
order.paidA purchase or a subscription renewal is paid. Includes the license keys.
order.refundedAn order is refunded, fully or partly.
subscription.updatedA subscription renews, changes status, or is canceled.
waitlist.joinedSomeone joins a product's waitlist.

The request

A POST with a JSON body and these headers:

Plumtier-Eventheaderrequired

The event name, like order.paid.

Plumtier-Deliveryheaderrequired

The delivery id. It's the same on retries, so use it to ignore repeats.

Plumtier-Signatureheaderrequired

t=<unix seconds>,v1=<hex>: an HMAC-SHA256 of <t>.<raw body> with your endpoint's secret.

order.paid
{
  "id": "whd_4k2m…",
  "event": "order.paid",
  "created_at": "2026-11-17T10:12:44.000Z",
  "data": {
    "order": {
      "id": "ord_q3fq…",
      "number": 1042,
      "kind": "purchase",
      "status": "paid",
      "product_id": "prod_s64g…",
      "product_name": "PastePal",
      "variant_id": "var_82vd…",
      "variant_name": "Family",
      "email": "ada@example.com",
      "customer_name": "Ada Lovelace",
      "country": "GB",
      "provider": "stripe",
      "mode": "live",
      "currency": "usd",
      "subtotal": 4900,
      "discount": 980,
      "discount_code": "LAUNCH20",
      "tax": 784,
      "total": 4704,
      "refunded": 0,
      "subscription_id": null,
      "affiliate_id": null,
      "paid_at": 1794909069
    },
    "license_keys": [
      { "key": "7KQ2M-XW9PA-4TB8N-R2HDE", "status": "active", "activation_limit": 5, "expires_at": null }
    ]
  }
}

Money is in minor units of currency (4704 is $47.04); paid_at and current_period_end are Unix seconds. order.refunded has the same data with the updated status and refunded. kind is renewal for subscription payments after the first.

subscription.updated
{
  "id": "whd_9s1x…",
  "event": "subscription.updated",
  "created_at": "2026-12-17T10:00:03.000Z",
  "data": {
    "subscription": {
      "id": "subn_7d3k…",
      "provider": "stripe",
      "status": "active",
      "product_id": "prod_s64g…",
      "email": "ada@example.com",
      "amount": 400,
      "currency": "usd",
      "interval": "month",
      "interval_count": 1,
      "current_period_end": 1797501069,
      "cancel_at_period_end": false,
      "canceled_at": null
    }
  }
}

Subscription status is trialing, active, past_due, paused, canceled or expired.

waitlist.joined
{
  "id": "whd_2b8n…",
  "event": "waitlist.joined",
  "created_at": "2026-11-17T08:30:00.000Z",
  "data": { "email": "grace@example.com", "product_id": "prod_k1m2…", "product_name": "Orbit" }
}

Verify the signature

Check every request before trusting it. Use the raw body exactly as received, and reject timestamps older than five minutes.

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

export function verifyPlumtier(rawBody, header, secret) {
  const t = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(header)?.[1];
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Answering and retries

  • Answer with any 2xx within 8 seconds. Do slow work after answering.
  • Anything else is retried after 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then marked failed.
  • Every delivery and its response is listed in Settings → Webhooks, where you can retry by hand or send a test event.
  • Deliveries can arrive more than once or out of order. Use Plumtier-Delivery to skip repeats and the order's status as the truth.