Business OS · Documentação

#Porém e erros comuns

#Os "porém" que mais derrubam

  1. A assinatura nunca bate. Quase sempre é o corpo: você leu o JSON já convertido em vez do corpo cru. Veja Assinatura.
  2. O segredo está errado por um detalhe. O segredo whsec_... é base64: o HMAC usa os bytes decodificados, não o texto.
  3. Processou duas vezes. O mesmo aviso pode chegar de novo (retry). Guarde o webhook-id. Veja Entrega.
  4. A ordem é outra. Não suponha que payment.approved chega antes de payment.refunded. Use subject.sequence e occurred_at.
  5. Tirou acesso no pedido de reembolso. refund.requested não é reembolso.
  6. Tirou acesso no cancelamento. Cancelar não é perder acesso: o fim vem com access.ended.
  7. Boas-vindas todo mês. Cobrança recorrente é um payment.approved novo a cada ciclo. Use access.started.
  8. Contou a renovação duas vezes. Renovação paga = payment.approved + subscription.renewed (+ access.renewed).
  9. Decidiu acesso por dois fluxos. Escolha UM.
  10. Liberou um teste. Confira is_test.
  11. Respondeu devagar. Passou de 15 s? O aviso será reenviado.
  12. Respondeu 410 sem querer. 410 Gone desliga o destino na hora.
  13. Rejeitou um campo novo. Campos novos podem aparecer. Ignore o que não conhece.
  14. Tratou null como zero. null é "não sabemos" ou "não se aplica".
  15. Usou ponto flutuante para dinheiro. Valores são inteiros em centavos.
  16. Comparou datas como texto local. Todas são UTC (terminando em Z).

#Erros que você pode ver

#No seu servidor

SintomaCausa provávelCorreção
Nunca recebo nadaHost fora da lista de permitidos, destino em rehearsal/approval/disabled, aviso em quarentena, ou interruptor global desligadoPeça à equipe para conferir. Veja Testes e quarentena.
Recebi e depois parou5 dias seguidos de falhas desligam o destino, ou você respondeu 410Corrija a causa e peça para religar.
Recebo repetidoRetry porque você demorou ou respondeu não 2xxResponda 2xx rápido e use o webhook-id.
Recebo x-kb-attempt: 2 ou maisSeu primeiro 2xx não chegou a nósVeja os logs da sua resposta; o proxy pode ter cortado.
timestamp fora da tolerânciaRelógio do servidor errado, ou você demora mais de 5 min para conferirLigue o NTP. Confira a assinatura logo ao receber.
JSON não confere com o exemploHá campo novo (aditivo) ou o objeto é de outro fluxoIgnore o extra. Confira type e o fluxo.
O host usa certificado inválidoSó enviamos para https com certificado válidoCorrija o certificado.

#Na API de leitura (/v1)

As rotas de leitura respondem erros neste formato:

{ "ok": false, "error": "invalid_cursor", "message": "..." }
StatuserrorQuando aconteceO que fazer
400invalid_queryParâmetro de busca inválidoConfira os parâmetros.
400invalid_cursorCursor adulterado ou antigoRecomece sem cursor.
400invalid_rangeIntervalo de datas inválidoConfira início e fim.
401unauthorizedSem o cabeçalho Authorization: Bearer ... (token na URL não vale) ou token inválidoMande o token no cabeçalho.
403forbiddenO 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.
404not_foundO recurso não existeConfira o id.
405method_not_allowedMétodo errado (as rotas de webhooks são só GET)Use GET.
503unavailableO servidor ainda não consegue responder (por exemplo, banco indisponível)Tente de novo mais tarde.
500internal_errorErro nossoAvise 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


← Testes e quarentena  ·  Teste ao vivo (em breve) →