Webhooks por conta

Webhooks pertencem à credencial que os registrou. No modo BaaS isso significa:

• Eventos de abertura de conta (ACCOUNT_REGISTER_*) → registre com a API Master
• Eventos de movimento de uma conta (cobrança paga, Pix recebido…) → registre com o AppID daquela conta

Registrando um webhook

curl --request POST \
  --url https://api.woovi.com/api/v1/webhook \
  --header 'Authorization: <APP_ID_DA_CONTA>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "webhook": {
      "name": "pagamentos conta cliente 001",
      "event": "OPENPIX:CHARGE_COMPLETED",
      "url": "https://minhaurl.exemplo/webhook/conta-001",
      "authorization": "meu-token-de-verificacao",
      "isActive": true
    }
  }'

No registro, a Woovi faz um handshake: sua URL recebe um POST de teste e precisa responder 200. Para pular essa validação, adicione ?validate=false à URL do endpoint. A resposta do registro inclui um hmacSecretKey, usado na validação de assinatura.

Eventos mais úteis no BaaS

Evento	Dispara quando	Registrar com
OPENPIX:CHARGE_COMPLETED	uma cobrança da conta é paga	AppID da conta
OPENPIX:TRANSACTION_RECEIVED	a conta recebe um Pix	AppID da conta
OPENPIX:MOVEMENT_CONFIRMED / OPENPIX:MOVEMENT_FAILED	um envio de Pix da conta é confirmado / falha	AppID da conta
OPENPIX:TRANSACTION_REFUND_RECEIVED	a conta recebe uma devolução	AppID da conta
ACCOUNT_REGISTER_APPROVED / _REJECTED / _PENDING	um registro de conta muda de status	API Master

A lista completa de eventos está em GET /api/v1/webhook/events e em Tipos de eventos de webhook.

Um endpoint por conta ou um único endpoint?

Os dois funcionam. Com muitas contas, prefira um único endpoint no seu sistema e identifique a conta pelo caminho da URL registrada (ex.: /webhook/conta-001) ou pelo header authorization configurado em cada webhook.

Limites e segurança

• Máximo de 50 webhooks por empresa; a mesma combinação de URL + evento não pode se repetir
• Valide a assinatura x-webhook-signature de cada entrega — veja Validação de assinatura
• Restrinja a origem aos IPs oficiais da Woovi — veja IPs de webhook