Skip to content

PHPAY-161: corrigir — o Inter não acrescenta /pix à URL do webhook - #162

Merged
mariolucasdev merged 1 commit into
developfrom
doc/phpay-161
Oct 25, 2026
Merged

mariolucasdev merged 1 commit into
developfrom
doc/phpay-161

Conversation

@mariolucasdev

Copy link
Copy Markdown
Collaborator

Closes #161.

A documentação do gateway do Inter, entregue no #156, afirmava que ele entrega a
notificação em <webhookUrl>/pix em vez da URL cadastrada. Está errado, e a
afirmação é minha.

De onde saiu

Da expressão que o Redoc mostra na seção de callback do webhookPut:

POST {$request.body#/webhookUrl/pix}

Li o /pix como caminho acrescentado. Lida como JSON Pointer — que é o que
#/ introduz — essa expressão é malformada: aponta para uma propriedade pix
dentro de webhookUrl, que é string. A explicação é outra: no OpenAPI um
callback tem nome, ali o nome é pix, e o Redoc juntou o nome à expressão.

callbacks:
  pix:                                  # ← o nome
    '{$request.body#/webhookUrl}':      # ← a expressão, bem formada
      post: ...

A documentação do Inter descreve o callback como POST na webhookUrl
cadastrada, e o exemplo dela — https://pix.example.com/api/webhook/ — não tem
sufixo.

O sufixo /pix existe: é quirk documentado do Itaú
(bacen/pix-api#313), que
implementa a mesma especificação. Foi daí que a confusão veio.

O código nunca esteve errado

Nada no Resources/Webhook/Webhook.php reescreve a URL — manda o que o chamador
passou, que é o correto nos dois cenários. O teste que fixa essa propriedade
continua valendo; mudaram o nome dele e o motivo no comentário.

Então isto é correção de seis textos, não de comportamento: o PHPDoc da
classe, docs/gateways/inter.md, a seção de notas do CHANGELOG.md, as
particularidades do CLAUDE.md, o teste e o exemplo.

O texto novo diz por que a afirmação parecia verdadeira

De propósito. Quem for conferir a referência do Inter vai topar com a mesma
expressão, e um aviso dizendo apenas "não acrescenta /pix" convidaria a
"consertar" o Resource de volta. O CLAUDE.md ganhou a frase explícita: não
acrescente o sufixo.

Fora destes arquivos, as notas da release v2.8.0 e um comentário no #156
carregam a mesma afirmação; corrijo os dois à mão, já que não são versionados.

Verificação

composer test: lint, 743 testes, PHPStan nível 9, 113 links. Smoke com 97
verificações. Nada mudou de comportamento, como esperado.

The gateway documentation claimed Inter delivers to <webhookUrl>/pix instead
of the URL you registered. It does not.

The claim came from the expression Redoc shows in the webhookPut callback
section: POST {$request.body#/webhookUrl/pix}. Read as a JSON Pointer, which
is what #/ introduces, that is malformed — it would point at a `pix` property
inside a string. What actually happened is that the callback is named `pix` in
the spec and Redoc joined the name to the expression. Inter's own text
describes a POST to the registered webhookUrl, and its example carries no
suffix.

The /pix suffix is real, but it is a documented quirk of Itaú, which
implements the same specification. That is where the confusion came from.

The code was never wrong: nothing rewrites the URL, which is correct either
way, and the test that fixes that property still holds — only its name and
its rationale change. The replacement text records why the claim looked true,
because anyone checking the reference will meet that expression again.
@mariolucasdev
mariolucasdev merged commit 5e2e75a into develop Oct 25, 2026
8 checks passed
@mariolucasdev
mariolucasdev deleted the doc/phpay-161 branch October 25, 2026 02:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Corrigir: o Inter não acrescenta /pix à URL do webhook

1 participant