#Porém e erros comuns
#Os "porém" que mais derrubam
- A assinatura nunca bate. Quase sempre é o corpo: você leu o JSON já convertido em vez do corpo cru. Veja Assinatura.
- O segredo está errado por um detalhe. O segredo
whsec_...é base64: o HMAC usa os bytes decodificados, não o texto. - Processou duas vezes. O mesmo aviso pode chegar de novo (retry). Guarde o
webhook-id. Veja Entrega. - A ordem é outra. Não suponha que
payment.approvedchega antes depayment.refunded. Usesubject.sequenceeoccurred_at. - Tirou acesso no pedido de reembolso.
refund.requestednão é reembolso. - Tirou acesso no cancelamento. Cancelar não é perder acesso: o fim vem com
access.ended. - Boas-vindas todo mês. Cobrança recorrente é um
payment.approvednovo a cada ciclo. Useaccess.started. - Contou a renovação duas vezes. Renovação paga =
payment.approved+subscription.renewed(+access.renewed). - Decidiu acesso por dois fluxos. Escolha UM.
- Liberou um teste. Confira
is_test. - Respondeu devagar. Passou de 15 s? O aviso será reenviado.
- Respondeu 410 sem querer.
410 Gonedesliga o destino na hora. - Rejeitou um campo novo. Campos novos podem aparecer. Ignore o que não conhece.
- Tratou
nullcomo zero.nullé "não sabemos" ou "não se aplica". - Usou ponto flutuante para dinheiro. Valores são inteiros em centavos.
- Comparou datas como texto local. Todas são UTC (terminando em
Z).
#Erros que você pode ver
#No seu servidor
| Sintoma | Causa provável | Correção |
|---|---|---|
| Nunca recebo nada | Host fora da lista de permitidos, destino em rehearsal/approval/disabled, aviso em quarentena, ou interruptor global desligado | Peça à equipe para conferir. Veja Testes e quarentena. |
| Recebi e depois parou | 5 dias seguidos de falhas desligam o destino, ou você respondeu 410 | Corrija a causa e peça para religar. |
| Recebo repetido | Retry porque você demorou ou respondeu não 2xx | Responda 2xx rápido e use o webhook-id. |
Recebo x-kb-attempt: 2 ou mais | Seu primeiro 2xx não chegou a nós | Veja os logs da sua resposta; o proxy pode ter cortado. |
timestamp fora da tolerância | Relógio do servidor errado, ou você demora mais de 5 min para conferir | Ligue o NTP. Confira a assinatura logo ao receber. |
| JSON não confere com o exemplo | Há campo novo (aditivo) ou o objeto é de outro fluxo | Ignore o extra. Confira type e o fluxo. |
| O host usa certificado inválido | Só enviamos para https com certificado válido | Corrija o certificado. |
#Na API de leitura (/v1)
As rotas de leitura respondem erros neste formato:
{ "ok": false, "error": "invalid_cursor", "message": "..." }
| Status | error | Quando acontece | O que fazer |
|---|---|---|---|
| 400 | invalid_query | Parâmetro de busca inválido | Confira os parâmetros. |
| 400 | invalid_cursor | Cursor adulterado ou antigo | Recomece sem cursor. |
| 400 | invalid_range | Intervalo de datas inválido | Confira início e fim. |
| 401 | unauthorized | Sem o cabeçalho Authorization: Bearer ... (token na URL não vale) ou token inválido | Mande o token no cabeçalho. |
| 403 | forbidden | O token não tem permissão para esta rota (cada token tem um papel que define as rotas que ele acessa) | Peça à KB um token com a permissão certa. |
| 404 | not_found | O recurso não existe | Confira o id. |
| 405 | method_not_allowed | Método errado (as rotas de webhooks são só GET) | Use GET. |
| 503 | unavailable | O servidor ainda não consegue responder (por exemplo, banco indisponível) | Tente de novo mais tarde. |
| 500 | internal_error | Erro nosso | Avise a equipe com o horário. |
Toda resposta traz source e coverage (de onde vem o dado e quanto dele está coberto). A paginação usa um cursor opaco: devolva nextCursor sem tentar interpretá-lo.
#Antes de pedir ajuda, junte
- o
webhook-iddo aviso; - o horário aproximado (UTC);
- o que o seu servidor respondeu (status e corpo);
- a rota
GET /v1/webhooks/endpoints/:id/attemptsmostra cada tentativa que fizemos: confira antes.