Skip to content
RugWard
RugWard Documentação
🌐 Português ▾
☰ Menu

RugWard Pay

Webhooks e verificação de assinatura

Receba uma notificação HTTPS assinada a cada mudança de status de uma fatura, verifique-a em curl, Node.js, Python ou PHP e trate novas tentativas e duplicatas com segurança.

Nesta página

Como os webhooks funcionam#

Quando uma fatura muda de status, a RugWard envia um POST com corpo JSON para o seu endpoint. Cada requisição é assinada com o seu segredo de assinatura (signing secret), para que você possa provar que veio da RugWard e não foi alterada.

Configurações do webhook
A caixa Webhook: URL do endpoint, New signing secret, Send test ping e o registro de entregas

Configuração#

  1. No painel, informe seu endpoint em Webhook e clique em Save.
  2. O segredo de assinatura (whsec_ seguido de 40 caracteres) é exibido uma única vez. Guarde-o no seu servidor, junto à chave de API.
  3. Clique em Send test ping. O painel mostra o status HTTP que o seu endpoint retornou.
  4. O registro de entregas abaixo da caixa mostra cada evento, seu resultado e o número de tentativas.

Regras do endpoint:

  • somente https://, na porta padrão (sem :8443), no máximo 500 caracteres;
  • um nome de host público: endereços IP, localhost e redes privadas são recusados;
  • responda em até 10 segundos com qualquer status 2xx. Redirecionamentos não são seguidos: uma resposta 3xx conta como falha.

New signing secret substitui o segredo imediatamente; implante o novo na hora (assinaturas feitas com o segredo antigo param de valer na hora). Salvar uma URL vazia desativa os webhooks.

Eventos#

EventoEnviado quando
invoice.pendingum pagamento foi visto, aguardando confirmações ou o restante do valor
invoice.paidtotalmente paga e confirmada: envie o pedido
invoice.overpaidpaga com mais de 1% a mais: envie o pedido
invoice.underpaido travamento da cotação terminou com pouco valor confirmado
invoice.lateum pagamento chegou após o vencimento
invoice.expiredvenceu sem pagamento
invoice.canceledvocê a cancelou
pingo botão Send test ping do painel

Cada evento é disparado no máximo uma vez por fatura. Faturas de teste nunca enviam webhooks.

A requisição#

Webhook request (what your endpoint receives)
POST /rugward-webhook HTTP/1.1
Host: shop.example
Content-Type: application/json
User-Agent: RugWard-Pay-Webhook/1.0
RugWard-Event-Id: Zx3kQ8pL2mN7vR1tY5wB9c:paid
RugWard-Event: invoice.paid
RugWard-Signature: t=1793324105,v1=5f0c3d0e8b1a…(64 hex characters)
Body: invoice.paid
{
  "id": "Zx3kQ8pL2mN7vR1tY5wB9c:paid",
  "type": "invoice.paid",
  "created": 1793324100,
  "data": {
    "invoice": {
      "id": "Zx3kQ8pL2mN7vR1tY5wB9c",
      "status": "paid",
      "amountUsd": "25.00",
      "orderId": "1234",
      "description": "1 x T-shirt, size M",
      "redirectUrl": "https://shop.example/thanks?order=1234",
      "createdAt": 1793323282069,
      "expiresAt": 1793326882069,
      "paidAt": 1793324100512,
      "assets": ["BTC", "ETH-8453", "USDC-8453"],
      "test": false,
      "quotes": [{ "id": 4711, "asset": "USDC-8453", "amount": "25.000629", "rateUsd": "1", "address": "0x…", "expiresAt": 1793325082069 }],
      "payments": [{ "txid": "0x…", "asset": "USDC-8453", "amount": "24.875626", "confirmations": 30, "required": 30, "confirmed": true, "seenAt": 1793324012000, "explorer": "https://basescan.org/tx/0x…" }]
    }
  }
}
Body: test ping (dashboard button)
{ "id": "ping:1793324000000", "type": "ping", "created": 1793324000, "data": {} }
  • id é <invoice id>:<status> e também está no cabeçalho RugWard-Event-Id: use-o para ignorar duplicatas.
  • created está em segundos Unix; data.invoice é o mesmo objeto retornado por GET /api/pay/merchant/invoices/:id.

Verificar a assinatura#

O cabeçalho tem este formato: RugWard-Signature: t=1793324100,v1=5f2c… (64 caracteres hexadecimais).

  1. Leia o corpo bruto da requisição exatamente como recebido (antes de qualquer parsing JSON).
  2. Calcule HMAC-SHA256(secret, t + "." + raw_body) e codifique em hexadecimal.
  3. Compare com v1 em tempo constante.
  4. Rejeite a requisição se t estiver a mais de 5 minutos do seu relógio (impede replays).
  5. Só então faça o parsing do JSON.

Fazer o parsing do JSON primeiro e serializá-lo de novo altera os bytes e quebra a assinatura. Sempre verifique a assinatura no corpo bruto.

Node.js (Express): verify, then process
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.RUGWARD_WEBHOOK_SECRET; // whsec_…
const app = express();

// Use the RAW body: the signature covers the exact bytes RugWard sent.
app.post("/rugward-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get("RugWard-Signature") || "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return res.sendStatus(400);
  const want = crypto.createHmac("sha256", SECRET).update(`${m[1]}.${raw}`).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]))) return res.sendStatus(400);

  const event = JSON.parse(raw);
  // De-duplicate: the same event id can arrive more than once.
  // if (alreadyProcessed(event.id)) return res.sendStatus(200);
  if (event.type === "invoice.paid" || event.type === "invoice.overpaid") {
    const inv = event.data.invoice;
    // markOrderPaid(inv.orderId, inv.id);  // ship only now
  }
  res.sendStatus(200); // any 2xx = delivered
});
app.listen(3000);
Python (Flask)
import hashlib, hmac, json, os, re, time
from flask import Flask, abort, request

SECRET = os.environ["RUGWARD_WEBHOOK_SECRET"].encode()  # whsec_…
app = Flask(__name__)

@app.post("/rugward-webhook")
def rugward_webhook():
    raw = request.get_data()  # raw bytes, exactly as sent
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", request.headers.get("RugWard-Signature", ""))
    if not m or abs(time.time() - int(m.group(1))) > 300:
        abort(400)
    want = hmac.new(SECRET, m.group(1).encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, m.group(2)):
        abort(400)
    event = json.loads(raw)
    if event["type"] in ("invoice.paid", "invoice.overpaid"):
        inv = event["data"]["invoice"]
        # mark_order_paid(inv["orderId"], inv["id"])  # de-duplicate on event["id"]
    return "", 200
PHP 8
<?php
$secret = getenv("RUGWARD_WEBHOOK_SECRET"); // whsec_…
$raw = file_get_contents("php://input");
$sig = $_SERVER["HTTP_RUGWARD_SIGNATURE"] ?? "";
if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $sig, $m) || abs(time() - (int)$m[1]) > 300) {
    http_response_code(400); exit;
}
$want = hash_hmac("sha256", $m[1] . "." . $raw, $secret);
if (!hash_equals($want, $m[2])) { http_response_code(400); exit; }

$event = json_decode($raw, true);
if (in_array($event["type"], ["invoice.paid", "invoice.overpaid"], true)) {
    $inv = $event["data"]["invoice"];
    // mark_order_paid($inv["orderId"], $inv["id"]); // de-duplicate on $event["id"]
}
http_response_code(200);

Para testar seu endpoint manualmente, assine um corpo você mesmo:

Shell (openssl): compute a signature to test your endpoint
SECRET='whsec_…'            # your signing secret
BODY='{"id":"ping:1","type":"ping","created":1793324000,"data":{}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST https://shop.example/rugward-webhook \
  -H "Content-Type: application/json" \
  -H "RugWard-Event: ping" \
  -H "RugWard-Signature: t=$T,v1=$SIG" \
  --data "$BODY"

Novas tentativas e duplicatas#

Se o seu endpoint exceder o tempo ou não responder 2xx, a RugWard tenta novamente: até 4 tentativas no total, após cerca de 30 segundos, 2 minutos e 8 minutos. Depois disso, o evento é marcado como falho no registro de entregas. Portanto, seu handler deve:

  • responder 2xx rapidamente e fazer o trabalho lento depois;
  • ser idempotente: armazene RugWard-Event-Id e ignore eventos já processados;
  • não depender da ordem: em caso de dúvida, releia a fatura pela API.

Webhooks são um sinal rápido, não o único. Se o seu servidor ficou fora do ar por um tempo, liste as faturas recentes pela API e compare os status.

Solução de problemas#

SintomaCausa provável
"Webhook URL must be https:// with a public host name"um endereço IP, uma porta personalizada, http:// ou um nome de host interno
o ping mostra HTTP 301/302/308seu servidor redireciona (por exemplo http→https, ou falta a barra final); use a URL final
o ping mostra 405a rota não aceita POST
a assinatura nunca confereo corpo foi analisado ou recodificado antes do hash, o segredo errado está em uso (após New signing secret) ou o relógio do servidor está errado
nenhum evento para faturas de testeesperado: faturas de teste nunca enviam webhooks

Última atualização: 30 de outubro de 2026

Webhooks e verificação de assinatura · RugWard Documentação | RugWard