Webhooks
Signed events sent to your own server when orders, refunds, subscriptions and waitlists change.
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
| Event | Sent when |
|---|---|
order.paid | A purchase or a subscription renewal is paid. Includes the license keys. |
order.refunded | An order is refunded, fully or partly. |
subscription.updated | A subscription renews, changes status, or is canceled. |
waitlist.joined | Someone joins a product's waitlist. |
The request
A POST with a JSON body and these headers:
Plumtier-EventheaderrequiredThe event name, like order.paid.
Plumtier-DeliveryheaderrequiredThe delivery id. It's the same on retries, so use it to ignore repeats.
Plumtier-Signatureheaderrequiredt=<unix seconds>,v1=<hex>: an HMAC-SHA256 of <t>.<raw body> with your endpoint's secret.
{
"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.
{
"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.
{
"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));
}import hashlib, hmac, re, time
def verify_plumtier(raw_body: bytes, header: str, secret: str) -> bool:
t = re.search(r"t=(\d+)", header)
v1 = re.search(r"v1=([0-9a-f]+)", header)
if not t or not v1 or abs(time.time() - int(t.group(1))) > 300:
return False
signed = t.group(1).encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1.group(1))Answering and retries
- Answer with any
2xxwithin 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-Deliveryto skip repeats and the order'sstatusas the truth.