Payment Gateway Sign in

Webhooks

The gateway sends an HTTP POST with a JSON body to each of the project's webhook endpoints. Create endpoints, choose which events each receives and send test events in the console.

{
  "id": "evt_...",
  "type": "payment.paid",
  "created": 1767225600,
  "data": {"payment": {"id": "...", "status": "paid", "reference": "order-1"}, "detail": {}}
}

Withdrawal events carry data.withdrawal instead of data.payment. Subscription events carry data.subscription and data.payment, which is null when there is no payment. See subscriptions.

Headers

  • X-Gateway-Event-Id: the event id. Deduplicate on it, deliveries are at least once.
  • X-Gateway-Signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256(secret, "{t}.{body}") over the raw request body.

Events

payment.paid, payment.expired, payment.cancelled, payment.late_payment, payment.disputed, payment.dispute_closed, attempt.failed, refund.completed, refund.failed, withdrawal.requested, withdrawal.completed, withdrawal.failed, subscription.created, invoice.paid, invoice.failed, invoice.payment_required, subscription.past_due, subscription.cancelled, subscription.paused, subscription.resumed, subscription.updated, platform.invoice.created, platform.invoice.paid, platform.invoice.past_due, platform.invoice.waived. payment.disputed fires when a card or PayPal dispute opens and payment.dispute_closed when it is decided. The payment carries disputed and dispute_status (open, won or lost). Ignore event types you do not know, new ones can be added.

Delivery and retries

Answer with any 2xx status to accept. Anything else, or a timeout, is retried with growing delays for three days, always with the same event id. After that the delivery is abandoned and an operator can replay it. You can also pull the same events from GET /v1/events, or poll GET /v1/payments/{id}.

Verifying a signature

Verify against the raw body, not a re-serialised copy. Reject timestamps more than five minutes from now, and compare in constant time.

The JavaScript (clients/js), Rust (clients/rust) and Python (clients/python) client libraries in clients/ ship a verifyWebhook helper, so you can use one of them instead of the samples below.

JavaScript (Node)

const crypto = require("node:crypto");

function verify(secret, header, body, nowSeconds, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp) || !parts.v1) return false;
  if (Math.abs(nowSeconds - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest();
  const given = Buffer.from(parts.v1, "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

module.exports = { verify };

Python

import hashlib
import hmac


def verify(secret, header, body, now_seconds, tolerance_seconds=300):
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        timestamp = int(parts["t"])
        given = bytes.fromhex(parts["v1"])
    except (KeyError, ValueError):
        return False
    if abs(now_seconds - timestamp) > tolerance_seconds:
        return False
    signed = f"{timestamp}.{body}".encode()
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).digest()
    return hmac.compare_digest(given, expected)

Rust

The Rust sample needs the hmac, sha2 and hex crates.

use hmac::{Hmac, Mac};
use sha2::Sha256;

pub fn verify_webhook(secret: &str, header: &str, body: &str, now: i64, tolerance: i64) -> bool {
    let mut timestamp = None;
    let mut signature = None;
    for part in header.split(',') {
        match part.split_once('=') {
            Some(("t", v)) => timestamp = v.parse::<i64>().ok(),
            Some(("v1", v)) => signature = hex::decode(v).ok(),
            _ => {}
        }
    }
    let (Some(timestamp), Some(signature)) = (timestamp, signature) else {
        return false;
    };
    if (now - timestamp).abs() > tolerance {
        return false;
    }
    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("hmac accepts any key length");
    mac.update(format!("{timestamp}.{body}").as_bytes());
    mac.verify_slice(&signature).is_ok()
}