Troubleshooting

​

401 Unauthorized

​

403 Forbidden

​

400 Saldo ou transferência

​

Webhook não chega

1. URL HTTPS em produção
2. Endpoint responde 2xx dentro do timeout
3. Eventos inscritos (payment.paid, etc.)
4. Transação criada pela mesma API key do endpoint
5. Verifique entregas falhas em Integrações → Webhooks no dashboard

Tutorial: Webhooks na prática.

​

Assinatura HMAC inválida

• Calcule HMAC sobre o raw body (bytes exatos)
• Use o whsec_... da criação do endpoint
• Header: x-WovePay-signature: sha256=<hex>
• Não re-serialize JSON antes de validar

​

QR PIX não confirma

• Prefira webhook payment.paid a polling agressivo
• QR expirado → payment.pix.expired ou status CANCELED
• Confirme trilho da chave compatível com a cobrança

​

429 Rate limit

100 requisições por minuto por chave. Backoff exponencial. Webhooks > polling. Rate limiting

​

Reembolso falha

Exige trilho PADRAO e depósito elegível com endToEndId. Use transactionId ou e2eId do depósito original.

​

Integração com IA gerou código errado

• Aponte o assistente para llms.txt e OpenAPI
• Confirme que a rota está no escopo v1
• Guia de integração com IA

​

Ainda com problema

Abra ticket no dashboard com:

• requestId da resposta de erro
• Horário UTC aproximado
• Rota e método HTTP
• ID da transação WovePay, se existir

Não envie wp_live_ completo nem whsec_ em tickets públicos.