Webhook Integration

Macropay is your Merchant of Record: we’re the seller on the customer’s statement, we collect and remit sales tax and VAT worldwide, and we run the billing ledger. Webhooks are how your application stays in lockstep with that ledger. Every time money moves, a subscription changes state, or a customer’s entitlements shift, we POST a signed event to your endpoint — so you can provision access, update your database, and react in real time without polling our API. This guide takes you from zero to a verified, production-ready handler.

What you’ll need

A Macropay account with an organization
An organization access token — see Authentication
An endpoint reachable over HTTPS (for local work, tunnel with ngrok)

Register an endpoint

Create the endpoint from the dashboard or the API. Either way, you’ll get back a signing secret (whsec_...) — store it like a password; you’ll use it to verify every delivery.

In the dashboard

Open your organization Settings → Webhooks
Click Add Endpoint
Paste your handler URL, e.g. https://your-app.com/api/webhooks/macropay
Tick the events you care about
Create, then copy the signing secret

Via the API

curl -X POST https://api.macropay.ai/v1/webhooks/endpoints \
  -H "Authorization: Bearer $MACROPAY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/api/webhooks/macropay",
    "events": [
      "order.paid",
      "order.refunded",
      "subscription.active",
      "subscription.revoked",
      "customer.state_changed"
    ],
    "format": "raw"
  }'

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN!,
  server: "sandbox",
});

const endpoint = await macropay.webhooks.endpoints.create({
  url: "https://your-app.com/api/webhooks/macropay",
  events: [
    "order.paid",
    "order.refunded",
    "subscription.active",
    "subscription.revoked",
    "customer.state_changed",
  ],
  format: "raw",
});

// Store this secret in your secrets manager — it's shown once.
console.log("Webhook secret:", endpoint.secret);

from macropay import Macropay
import os

client = Macropay(
    access_token=os.environ["MACROPAY_ACCESS_TOKEN"],
    server="sandbox",
)

endpoint = client.webhooks.endpoints.create(
    url="https://your-app.com/api/webhooks/macropay",
    events=[
        "order.paid",
        "order.refunded",
        "subscription.active",
        "subscription.revoked",
        "customer.state_changed",
    ],
    format="raw",
)

# Store this secret in your secrets manager — it's shown once.
print(f"Webhook secret: {endpoint.secret}")

Pick your events

“The customer just paid” → listen for order.paid. It is the single signal for money cleared, across every flow:

Flow	What fires on payment	Key field
One-time purchase	`order.paid`	—
Subscription — first payment	`order.paid` then `subscription.active`	`order.billing_reason = "subscription_create"`
Subscription — each renewal	`order.paid`	`order.billing_reason = "subscription_cycle"`

checkout.updated → status: succeeded is a funnel signal, not a fulfillment one — it can arrive before the order is fully paid. Grant access on order.paid, not on a checkout event. Distinguish one-time vs. subscription orders with order.subscription_id / order.billing_reason.

Subscribe to only what your integration acts on. A few of the most common:

Event	Fires when	Typical reaction
`order.paid`	A one-time or recurring payment clears	Grant the license key, unlock the download, mark the plan active
`order.refunded`	An order is refunded	Reverse the grant, adjust your records
`subscription.created`	A subscription is created	Start onboarding
`subscription.active`	A subscription becomes active	Provision the paid tier
`subscription.canceled`	A subscription is canceled (ends at period end)	Schedule downgrade for the period boundary
`subscription.revoked`	A subscription is cut off now (e.g. failed payment)	Revoke Discord / GitHub access immediately
`checkout.created`	A checkout session starts	Track funnel entry
`checkout.updated`	A checkout session’s status changes	Track funnel progress
`customer.created`	A new customer is created	Sync to your CRM
`customer.state_changed`	A customer’s active subscriptions or entitlements change	Re-evaluate access in one place

If you only want a single source of truth for “what does this customer have access to right now,” subscribe to customer.state_changed and read the entitlement set from the payload — it folds order and subscription changes into one signal. You can also query it on demand; see Customer State.

The full catalog — including events for usage-based meters and AI/agent billing — lives in the event reference.

Verify, then handle

Every delivery is signed using the Standard Webhooks spec and carries three headers: webhook-id, webhook-timestamp, and webhook-signature. Always verify against the raw request body before you trust a payload — never parse JSON first, or you’ll break the signature check.

Next.js (App Router)

// src/app/api/webhooks/macropay/route.ts
import { NextRequest, NextResponse } from "next/server";
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.MACROPAY_WEBHOOK_SECRET!);

export async function POST(req: NextRequest) {
  const body = await req.text(); // raw body — required for verification
  const headers = {
    "webhook-id": req.headers.get("webhook-id")!,
    "webhook-timestamp": req.headers.get("webhook-timestamp")!,
    "webhook-signature": req.headers.get("webhook-signature")!,
  };

  let payload: any;
  try {
    payload = wh.verify(body, headers);
  } catch {
    return NextResponse.json({ error: "invalid signature" }, { status: 401 });
  }

  switch (payload.type) {
    case "order.paid":
      // Fulfill: e.g. issue a license key for the purchased product
      await db.licenses.create({
        data: {
          customerEmail: payload.data.customer.email,
          product: payload.data.product.name,
        },
      });
      break;
    case "subscription.revoked":
      // Payment failed or access pulled — cut them off now
      await db.users.update({
        where: { id: payload.data.customer.id },
        data: { active: false },
      });
      break;
  }

  return NextResponse.json({ received: true });
}

FastAPI (Python)

from fastapi import FastAPI, Request, HTTPException
from standardwebhooks.webhooks import Webhook
import os

app = FastAPI()

@app.post("/api/webhooks/macropay")
async def handle_webhook(request: Request):
    body = await request.body()  # raw bytes — required for verification
    headers = {
        "webhook-id": request.headers.get("webhook-id"),
        "webhook-timestamp": request.headers.get("webhook-timestamp"),
        "webhook-signature": request.headers.get("webhook-signature"),
    }

    wh = Webhook(os.environ["MACROPAY_WEBHOOK_SECRET"])

    try:
        payload = wh.verify(body.decode("utf-8"), headers)
    except Exception:
        raise HTTPException(status_code=401, detail="Invalid signature")

    match payload["type"]:
        case "order.paid":
            order = payload["data"]
            # Provision access for order["product"]
        case "subscription.revoked":
            subscription = payload["data"]
            # Revoke access immediately

    return {"status": "ok"}

Express.js

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();

app.post(
  "/api/webhooks/macropay",
  express.raw({ type: "application/json" }), // keep the body raw
  (req, res) => {
    const body = req.body.toString();
    const headers = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
    };

    const wh = new Webhook(process.env.MACROPAY_WEBHOOK_SECRET!);

    try {
      const payload = wh.verify(body, headers);
      // Dispatch on payload.type
      res.status(200).send("OK");
    } catch {
      res.status(401).send("Invalid signature");
    }
  }
);

For a line-by-line walkthrough of the signing scheme, see Signature verification.

Test before you ship

Tunnel to localhost

ngrok http 3000

Use the public ngrok URL as your endpoint, e.g. https://abc123.ngrok-free.app/api/webhooks/macropay. Point your sandbox endpoint at it so test events never touch production.

Fire a real event

Spin up a checkout link for one of your products
Pay with the sandbox test card 4242 4242 4242 4242
Confirm the order.paid event lands at your handler and your fulfillment logic runs

Prefer to stay in the terminal? The Macropay CLI can replay and forward events to your local handler — see local webhook testing.

Harden for production

Deduplicate with `webhook-id`

The same event may be delivered more than once (that’s how at-least-once delivery guarantees nothing is lost). Treat webhook-id as an idempotency key:

const webhookId = req.headers.get("webhook-id");

const seen = await db.processedWebhooks.findUnique({
  where: { webhookId },
});

if (seen) {
  return new Response("Already processed", { status: 200 });
}

// ...do the work, then record it...
await db.processedWebhooks.create({ data: { webhookId } });

Acknowledge fast, work later

Verify the signature, hand the payload to a queue, and return 200 right away. Long-running fulfillment (emails, provisioning, third-party calls) belongs in a worker, not the request cycle:

export async function POST(req: Request) {
  const payload = verifyWebhook(req); // throws on bad signature
  await queue.publish("macropay-webhook", payload);
  return new Response("OK", { status: 200 });
}

Respond with a 2xx within 30 seconds. Anything else (or a timeout) is treated as a failure and retried with exponential backoff. See delivery & retries for the schedule and guarantees.

Where to go next

Event reference

Every event type and payload shape, including usage and agent-billing events

Signature verification

How Standard Webhooks signing works under the hood

Delivery & retries

Retry backoff, ordering, and delivery guarantees

Customer state

Query a customer’s live entitlements on demand

Bootup

Features

Integrate

Merchant of Record (MoR)

Webhook Integration

What you’ll need

Register an endpoint

In the dashboard

Via the API

Pick your events

Verify, then handle

Next.js (App Router)

FastAPI (Python)

Express.js

Test before you ship

Tunnel to localhost

Fire a real event

Harden for production

Deduplicate with `webhook-id`

Acknowledge fast, work later

Where to go next

Event reference

Signature verification

Delivery & retries

Customer state

​What you’ll need

​Register an endpoint

​In the dashboard

​Via the API

​Pick your events

​Verify, then handle

​Next.js (App Router)

​FastAPI (Python)

​Express.js

​Test before you ship

​Tunnel to localhost

​Fire a real event

​Harden for production

​Deduplicate with webhook-id

​Acknowledge fast, work later

​Where to go next

Event reference

Signature verification

Delivery & retries

Customer state

What you’ll need

Register an endpoint

In the dashboard

Via the API

Pick your events

Verify, then handle

Next.js (App Router)

FastAPI (Python)

Express.js

Test before you ship

Tunnel to localhost

Fire a real event

Harden for production

Deduplicate with `webhook-id`

Acknowledge fast, work later

Where to go next