Webhooks
Os avisos importantes (limite de um cliente atingido, fundo baixo, recarga automática, fatura emitida, pagamento que falhou, conector fora do ar) chegam por e-mail e no app, na Central do parceiro. Os webhooks abaixo são uma integração avançada e opcional, para automatizar no seu próprio sistema.
O Rook chama uma URL sua quando um cliente usa 80% do crédito do mês e de novo quando ele acaba. A URL precisa ser https e pública; ela e o segredo de assinatura são configurados com a equipe do Rook, que também pode trocar o segredo quando você pedir (o antigo deixa de valer).
O aviso
Seção intitulada “O aviso”POST com corpo JSON, enviado uma vez por cliente, tipo e mês:
{ "id": "evt_...", "type": "tenant.allowance_low", "createdAt": "2026-11-20T12:00:00.000Z", "externalTenantId": "loja-1", "period": "2026-11", "grantedCents": 1500, "usedCents": 1260, "remainingCents": 240}type é tenant.allowance_low ou tenant.allowance_exhausted. O corpo nunca traz chave, token ou conteúdo do cliente.
| Cabeçalho | Valor |
|---|---|
X-Rook-Event |
O type. |
X-Rook-Delivery |
O id, para deduplicar. |
X-Rook-Timestamp |
Segundos desde a época. |
X-Rook-Signature |
sha256=<hex>: HMAC-SHA256, com o segredo, de <timestamp>.<corpo bruto>. |
Verificar a assinatura
Seção intitulada “Verificar a assinatura”Calcule o HMAC sobre o corpo bruto (antes de interpretar o JSON), compare em tempo constante e rejeite timestamps com mais de alguns minutos.
import crypto from "node:crypto";import express from "express";
const app = express();
app.post("/rook/webhook", express.raw({ type: "application/json" }), (req, res) => { const timestamp = req.get("X-Rook-Timestamp") ?? ""; const received = req.get("X-Rook-Signature") ?? ""; const expected = "sha256=" + crypto .createHmac("sha256", process.env.ROOK_WEBHOOK_SECRET) .update(`${timestamp}.${req.body.toString("utf8")}`) .digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); if (!fresh || !valid) return res.sendStatus(401);
const event = JSON.parse(req.body); // deduplique por req.get("X-Rook-Delivery") console.log(event.type, event.externalTenantId); res.sendStatus(200);});import hashlib, hmac, os, timefrom flask import Flask, request, abort
app = Flask(__name__)SECRET = os.environ["ROOK_WEBHOOK_SECRET"].encode()
@app.post("/rook/webhook")def rook_webhook(): timestamp = request.headers.get("X-Rook-Timestamp", "") received = request.headers.get("X-Rook-Signature", "") body = request.get_data() # corpo bruto expected = "sha256=" + hmac.new( SECRET, f"{timestamp}.".encode() + body, hashlib.sha256 ).hexdigest()
fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300 if not fresh or not hmac.compare_digest(received, expected): abort(401)
event = request.get_json() # deduplique por request.headers["X-Rook-Delivery"] print(event["type"], event["externalTenantId"]) return "", 200Entrega e novas tentativas
Seção intitulada “Entrega e novas tentativas”Responda qualquer 2xx quando tiver tratado o aviso. Qualquer outra resposta, ou nenhuma em dez segundos, é tentada de novo com espera crescente (até 8 tentativas), e um aviso ainda não entregue volta à fila por até três dias. Por isso o seu tratador deve ser idempotente: use X-Rook-Delivery.
Em breve
Seção intitulada “Em breve”Com a API de comércio chegam subscription.updated, subscription.lapsed, credit.granted, credit.expired, invoice.issued e payout.paid, com a mesma assinatura e entrega.
Eventos de crédito (parceiros embutidos)
Seção intitulada “Eventos de crédito (parceiros embutidos)”customer.credit_limit_reached é enviado uma vez por cliente e mês, quando o cliente chega ao limite mensal de créditos que você definiu. partner.balance_low é enviado quando o seu fundo cai abaixo da parcela de saldo baixo, e de novo só depois de uma nova recarga; ele não tem externalTenantId, porque é sobre o fundo. Os valores são em créditos, não em moeda, e a assinatura e a entrega são as mesmas.
{ "type": "customer.credit_limit_reached", "externalTenantId": "clinic-1", "period": "2026-11", "limitCredits": 1000, "usedCredits": 1000 }{ "type": "partner.balance_low", "balanceCredits": 400, "thresholdBps": 2000, "currency": "BRL" }Avisos para a sua equipe
Seção intitulada “Avisos para a sua equipe”Quem gerencia o parceiro também é avisado dentro do app e por e-mail, sem precisar de webhook: cliente que atingiu o limite mensal, fundo de créditos acabando, recarga automática, nova fatura, pagamento em atraso e conector fora do ar. Vários avisos seguidos chegam em um único e-mail. Em Integração dá para desligar o e-mail de cada tipo; o aviso no app fica sempre ligado. O webhook continua opcional, para integrar com o seu sistema.