Webhook ingestion

Node.js

import crypto from "node:crypto";

function signPayload(secret, body) {
  const ts = Math.floor(Date.now() / 1000).toString();
  const sig = crypto.createHmac("sha256", secret)
    .update(`${ts}.${body}`)
    .digest("hex");
  return `t=${ts},v1=${sig}`;
}

const body = JSON.stringify({
  external_id: "order-12345",
  amount_usd: "0.50",
  amount_raw: "500000",
  currency: "USDC",
  network: "base",
  payer_address: "0xabc...",
  pay_to_address: "0xdef...",
  resource_path: "/api/things/42",
  payment_timestamp: new Date().toISOString(),
});

await fetch("https://getstubly.com/api/webhooks/<endpointId>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Stubly-Signature": signPayload(SECRET, body),
  },
  body,
});

Python

import hashlib, hmac, json, time
import requests

def sign_payload(secret, body):
    ts = str(int(time.time()))
    sig = hmac.new(
        secret.encode(),
        f"{ts}.{body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return f"t={ts},v1={sig}"

body = json.dumps({
    "external_id": "order-12345",
    "amount_usd": "0.50",
    "amount_raw": "500000",
    "currency": "USDC",
    "network": "base",
    "payer_address": "0xabc...",
    "pay_to_address": "0xdef...",
    "resource_path": "/api/things/42",
    "payment_timestamp": "2026-04-27T18:00:00Z",
})

requests.post(
    "https://getstubly.com/api/webhooks/<endpointId>",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Stubly-Signature": sign_payload(SECRET, body),
    },
)

curl

SECRET='whsec_...'
BODY='{"external_id":"order-12345","amount_usd":"0.50","amount_raw":"500000","currency":"USDC","network":"base","payer_address":"0xabc...","pay_to_address":"0xdef...","resource_path":"/api/things/42","payment_timestamp":"2026-04-27T18:00:00Z"}'
TS=$(date +%s)
SIG=$(printf '%s' "${TS}.${BODY}" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST https://getstubly.com/api/webhooks/<endpointId> \
  -H 'Content-Type: application/json' \
  -H "X-Stubly-Signature: t=${TS},v1=${SIG}" \
  -d "$BODY"

Receipt status values

The receipt_url field

receipt_url is a stable Stubly-hosted URL of the form https://getstubly.com/receipts/<receiptId>. It's safe to store and reuse — even if the underlying storage backend changes, this URL stays valid. GETting it returns:

• 302 redirect to the PDF when the receipt is ready. Browsers follow transparently; HTTP clients should follow redirects.
• 404when the receipt isn't ready yet, has failed, or doesn't exist.
• 503 with Retry-After: 30 if our database is briefly unreachable.

Polling pattern: if you need the PDF immediately after a payment lands, poll the URL every 2–3 seconds for ~15 seconds. A 302 means done. A persistent 404 past 30 seconds usually means a stuck or failed generation — check your dashboard.

Successful redirect responses include Cache-Control: public, max-age=3600, so repeated fetches of a ready receipt are fast.

What's on a v1 receipt

A single US Letter page, system fonts, no customer branding (yet). Content:

• Stubly + "RECEIPT" header, receipt ID, issue date
• Amount (large, prominent) + currency + raw chain amount
• Payer wallet address and payee wallet address, full, monospace
• Network, payment timestamp (UTC), resource path, your external_id
• Transaction hash if present in your raw_facilitator_response (we look for tx_hash, transaction_hash, txHash, or hash)
• Footer: "Generated by Stubly · getstubly.com"

Future template versions will add customer branding and additional fields. Existing receipts continue rendering with their original template version — receipts you have today will look the same forever.

Auto-email delivery

Include a payer_email field on your payload and Stubly will email the receipt directly to that address once the PDF is ready. The email contains a brief HTML body with a payment summary, a link to the Stubly receipt_url, and the PDF as an attachment.

• Sender: all emails come from receipts@getstubly.com. Customer-domain sending (using your own address as the From) is not currently supported — that's an enterprise-tier feature that requires per-customer DNS verification.
• Subject:"Receipt for your payment to [your business name] — $X.XX [CURRENCY]".
• Optional: omit payer_emailfrom your payload to skip auto-email. Existing integrations that don't send the field continue working unchanged.
• Format failures don't block payments. A malformed email address (e.g., "not-an-email") still results in a 200 response from the webhook and a successfully recorded payment event. The email side is marked Invalid email on your dashboard with the specific format issue.
• Bounces and complaints are surfaced.If the recipient's mail server rejects the message or marks it as spam, the dashboard shows a Bouncedbadge with the reason. Bounced receipts don't affect the underlying payment record, which remains valid; the receipt itself is also still accessible via the Stubly URL.
• Send timing: typically 5–15 seconds after the webhook is accepted (PDF generation + Resend send + recipient mail server acknowledgement).

If you don't have the payer's email at payment time, fetching the PDF yourself via receipt_url and forwarding it through your own system remains a fully supported path.

Security model

The receipt URL contains a high-entropy CUID (~150 bits). Anyone with the URL can fetch the PDF — that's by design, so you can embed receipts in emails, payer portals, or accountant exports without per-fetch authentication. Treat receipt URLs as semi-sensitive (similar to a password reset link): don't post them publicly, and don't share them more broadly than you need to. We can't revoke a leaked URL without re-issuing the receipt.