Registra endpoint de webhook

Cadastra uma URL HTTPS para receber eventos da conta. O authToken é fornecido por você na criação e enviado no header Authorization (sem prefixo Bearer) em cada requisição — armazene-o de forma segura.

POST/v1/pix-accounts/:accountId/webhooks

authToken é definido por você na criação — gere um segredo forte (UUID v4 ou bytes aleatórios em base64). A Stater envia exatamente esse valor no header Authorization (sem prefixo Bearer) em cada chamada ao seu endpoint. Compare time-safe (timingSafeEqual / hmac.compare_digest) para evitar ataques de timing.

Path params

accountIdObrigatório
string
ID da conta Pix.

Headers

AuthorizationObrigatório
string
Bearer SUA_API_KEY
Idempotency-KeyObrigatório
string
UUID para retry seguro.
Content-TypeObrigatório
string
application/json

Body

urlObrigatório
string (HTTPS)
Endpoint público que receberá os eventos.
eventsObrigatório
string[]
Tipos assinados. Valores aceitos: pix.in.received, pix.payout.succeeded, pix.payout.failed, pix.payout.cancelled, pix.payout.refunded, pix.charge.paid, pix.charge.expired, pix.charge.refunded.
authTokenObrigatório
string
Segredo forte (mín. 32 caracteres recomendados) que a Stater enviará no header Authorization (sem prefixo Bearer) em cada requisição. Você define o valor — não é gerado pela API.

Exemplo de requisição

bash

curl -X POST https://api.staterpay.io/v1/pix-accounts/cmoxample0001qkxyzaccount/webhooks \  -H "Authorization: Bearer SUA_API_KEY" \  -H "Idempotency-Key: cf6ecd19-3d46-4c3e-84c4-ea481e3be2d4" \  -H "Content-Type: application/json" \  -d '{    "url": "https://api.minhaempresa.com/webhooks/stater",    "events": [      "pix.payout.succeeded",      "pix.payout.failed",      "pix.payout.cancelled",      "pix.payout.refunded",      "pix.charge.paid",      "pix.charge.expired",      "pix.charge.refunded",      "pix.in.received"    ],    "authToken": "um-segredo-forte-gerado-por-voce"  }'

Resposta

id
string
Identificador do webhook.
pixAccountId
string
Conta Pix proprietária.
url
string
URL cadastrada (eco).
events
string[]
Eventos assinados (eco).
authToken
string
Token recém-cadastrado. Só aparece nesta criação — em listagens posteriores não vem.
coreEndpointId
string | null
ID do endpoint no core, quando espelhado.
enabled
boolean
Sempre true ao criar.
createdAt
string (ISO-8601 UTC-3)
Criação.

json

{  "id": "cmoxample0001qkxyzwebhook",  "pixAccountId": "cmoxample0001qkxyzaccount",  "url": "https://api.minhaempresa.com/webhooks/stater",  "events": [    "pix.payout.succeeded",    "pix.payout.failed",    "pix.payout.cancelled",    "pix.payout.refunded",    "pix.charge.paid",    "pix.charge.expired",    "pix.charge.refunded",    "pix.in.received"  ],  "authToken": "um-segredo-forte-gerado-por-voce",  "coreEndpointId": null,  "enabled": true,  "createdAt": "2026-05-07T19:16:09.996-03:00"}

URL base:https://api.staterpay.io

Registrar webhook