Skip to content

Webhooks

Signed events REM Payments sends to your endpoints - the event list, the envelope, headers, verification in Python and Node, retries and replays.

REM Payments POSTs a signed JSON event to each of your endpoints when something happens. Register endpoints under Webhooks > Endpoints or with POST /api/orgs/{org_id}/endpoints (write scope):

curl -X POST https://rempayments.com/api/orgs/1/endpoints -H "Authorization: Bearer $PTK" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/hooks/payments", "description": "Production", "app_id": null,
       "events": ["checkout.completed", "payment.captured", "subscription.cancelled"], "enabled": true}'

The answer contains secret (whsec_...) once. "events": [] means every event. POST /api/endpoints/{id}/test sends a ping at once and returns your server's answer.

Events

Event

When

checkout.completed, checkout.expired

A session was paid / expired

payment.captured, payment.failed, payment.refunded

Payment outcomes (mark-paid counts as captured)

subscription.activated

First activation (not renewals)

subscription.renewed

A period rolled; carries payment_id

subscription.past_due, subscription.cancelled, subscription.paused, subscription.resumed

State changes

invoice.created (with pay_url for renewals and manual invoices), invoice.paid, invoice.void

Invoices

refund.processed, refund.failed

Refund settled

customer.created

New customer

plan.price_scheduled

A price or feature reduction reaches a subscription: from/to amounts, features reduced, effective date

plan.retired

A plan stopped selling

entitlements.changed

What a customer may use changed

trial.started, trial.ending (3 days before), trial.ended, trial.converted

Trials

credits.granted, credits.clawed_back

REM Credits granted from a payment, or taken back on a refund

ping

Endpoint test

Envelope

{
  "event": "payment.captured",
  "created_at": "2026-11-18T09:14:03.120Z",
  "org": "your-org",
  "app": "your-app",
  "data": {"id": "pay_...", "status": "captured", "amount": 58882, "currency": "INR"},
  "id": "dlv_...",
  "attempt": 1
}

id is the delivery id, the same on every retry: store it and handle each id once. attempt counts tries.

Header

Value

X-PaymentsHub-Event

the event name

X-PaymentsHub-Delivery

the delivery id

X-PaymentsHub-Timestamp

unix seconds

X-PaymentsHub-Signature

t=<unix>,v1=<hex HMAC-SHA256(secret, "<unix>." + raw body)>

(The headers keep the service's technical name, PaymentsHub.)

Verify the signature

Verify the raw request bytes before parsing the JSON, and reject timestamps older than 5 minutes.

Python:

import hmac, hashlib, time

def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False
    mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])

Node (Express):

const crypto = require("crypto");

function verify(secret, header, rawBody, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
  return mac.length === parts.v1.length && crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(parts.v1));
}

app.post("/hooks/payments", express.raw({ type: "*/*" }), (req, res) => {
  if (!verify(process.env.PAYMENTS_WHSEC, req.get("X-PaymentsHub-Signature"), req.body)) return res.sendStatus(400);
  const evt = JSON.parse(req.body);
  // handle evt.event once per evt.id
  res.sendStatus(200);
});

With the Python SDK: verify_webhook(body, request.headers, secret) does the same and returns a parsed event.

Retries

Answer any 2xx within 15 seconds. Otherwise the delivery is retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h and 24 h; then it is exhausted and waits for POST /api/deliveries/{id}/retry (or Retry in the dashboard). Redirects are not followed. Rotate a secret with POST /api/endpoints/{id}/rotate-secret: old signatures stop validating at once, so deploy the new secret first.

Inbound webhooks from gateways

Gateways post to https://rempayments.com/api/webhooks/{provider}/{gateway id}. Each request is stored before it is checked, then verified, parsed, de-duplicated by the provider's event id and applied. POST /api/webhook-events/{id}/replay re-runs a stored one (safe: applying twice changes nothing).

Last updated 18 Nov 2026

Webhooks · REM Platforms Blog