Webhooks
Eventos & assinatura
Cadastre endpoints HTTPS para receber eventos da Stater. Cada endpoint tem um secret usado para assinar os payloads.
Criar endpoint
POST/v1/webhook-endpoints
Escopo: webhooks:manage.
urlstring (https)requiredURL pública para entrega.
eventsstring[]requiredLista de tipos a inscrever.
accountIduuidoptionalFiltra eventos só desta conta. Cliente restrito deve usar a própria conta ou omitir.
Secret só aparece uma vez
O campo secret só é retornado na criação. Guarde-o com segurança — é necessário para validar a assinatura.
Outras operações
GET/v1/webhook-endpoints
PATCH/v1/webhook-endpoints/:id
DELETE/v1/webhook-endpoints/:id
POST/v1/webhook-events/test
PATCH aceita url, events, enabled. DELETE responde 204 sem corpo. O endpoint de teste responde202 { "queued": true }.
Formato da entrega
O worker envia POST para sua url com:
json
{
"id": "<uuid>",
"type": "<eventType>",
"created_at": "<iso>",
"data": { }
}Cabeçalhos
| Header | Descrição |
|---|---|
| webhook-id | ID único do evento |
| webhook-timestamp | Unix em segundos |
| webhook-signature | HMAC-SHA256 hex de {timestamp}.{payload} com o secret |
Resposta esperada
Retorne qualquer 2xx para marcar a entrega como sucesso.
Verificando a assinatura (Node.js)
javascript
import crypto from "node:crypto";
function verify(req, secret) {
const ts = req.headers["webhook-timestamp"];
const sig = req.headers["webhook-signature"];
const payload = JSON.stringify(req.body);
const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${payload}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(sig, "hex"),
Buffer.from(expected, "hex"),
);
}Tipos de evento
| eventType | Quando |
|---|---|
| pix.deposit_qr.created | QR criado via API Stater |
| pix.deposit_qr.provider_webhook | Webhook do provedor de criação/sync de QR |
| pix.charge.completed | PIX in confirmado (inclui QR pago) |
| pix.charge.refunded | Estorno MED / chargeback |
| pix.charge.refund_error | Falha de estorno reportada pelo provedor |
| pix.payout.succeeded | PIX out concluído |
| pix.payout.failed | PIX out falhou |
| pix.payout.refunded | Reembolso de PIX out |
| webhook.test | Disparo manual de teste |