fix(webhooks): CRUD account-scoped /v2/webhooks + release v3.1.0 - #21
Merged
Conversation
…real da API
A rota company-scoped /v1/companies/{id}/webhooks retorna 404 incondicional
(confirmado em 3 contas, 2026-07-02/03) — o contrato havia sido herdado de
alucinação do SDK Node. O contrato real é account-scoped com envelope
{"webHook": {...}} nos dois sentidos.
- Novos métodos: listAccountWebhooks, createAccountWebhook,
retrieveAccountWebhook, updateAccountWebhook, deleteAccountWebhook,
deleteAllAccountWebhooks (destrutivo, nome distinto), pingAccountWebhook,
fetchEventTypes (lista viva — os literais invoice.* não existem)
- Novo DTO AccountWebhook com o shape real do fio (contentType/status
string; desvio vs enum int do spec pinado em teste de alinhamento YAML↔DTO)
- Métodos company-scoped e getAvailableEvents @deprecated, comportamento
inalterado; remoção na próxima major
- Gotchas documentados: NFE.io pinga a uri no create (exige 2xx), secret
32-64 chars ecoado só no create, PUT de update é substituição integral
- Docs, README, sample e skill atualizados para o fluxo account
Validado ao vivo (CRUD completo com webhook descartável): create 201,
retrieve com secret omitido, update 200, ping 204, delete 204 + 404.
OpenSpec: fix-account-webhooks-contract
|
Rastreabilidade retroativa (Review S11): #22 |
andrenfe
added a commit
that referenced
this pull request
Jul 7, 2026
Desde 45aa6e8 ("master passa a ser a linha canônica v3+"), o ci.yml continuou disparando apenas em push/PR da branch `v3`. Efeito: nenhum PR contra master rodou o CI funcional (matriz PHP 8.2/8.3/8.4 + PHPStan + CS + generate:check) — só o CodeQL. Confirmado nos PRs #21 (release v3.1.0) e #23. Adiciona `master` aos gatilhos push e pull_request (mantém `v3` por segurança; a branch ainda existe, congelada em v3.0.0). Mudança não-destrutiva, só de gatilho — sem uso de input não confiável.
This was referenced Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resumo
O CRUD de webhooks do SDK estava 100% quebrado contra a API real: a rota company-scoped
/v1/companies/{id}/webhooksretorna 404 incondicional (confirmado em 3 contas, 2026-07-02/03) — contrato herdado de alucinação do SDK Node. O contrato real é account-scoped:/v2/webhookscom envelope{"webHook": {...}}nos dois sentidos.Inclui também o commit de release v3.1.0 (bump de
Version.php+ CHANGELOG). Após o merge, a tagv3.1.0será criada na master (dispara orelease.yml).Mudanças
WebhooksResource:listAccountWebhooks,createAccountWebhook,retrieveAccountWebhook,updateAccountWebhook,deleteAccountWebhook,deleteAllAccountWebhooks(destrutivo, nome distinto),pingAccountWebhook,fetchEventTypes(lista viva — os literaisinvoice.*não existem)AccountWebhookcom o shape real do fio (contentType/statusstring; desvio vs enum int do spec OpenAPI pinado em teste de alinhamento YAML↔DTO)getAvailableEvents()+ DTOWebhook— comportamento inalterado, remoção na próxima majorurino create (exige 2xx);secret32–64 chars ecoado só no create;PUTde update é substituição integral (semstatus→ desativa o hook)apiVersion(): ''+ paths versionados explícitos (precedenteAddressesResource) — URLs company-scoped permanecem idênticas, zero mudança no coreValidação
api.nfe.iocom webhook descartável: create 201 (envelope aceito, secret ecoado, ping 2xx), retrieve com secret omitido, update PUT integral 200, ping 204, delete 204 + retrieve pós-delete 404; estado da conta preservado (9 webhooks antes/depois)OpenSpec:
fix-account-webhooks-contract(arquivado emopenspec/changes/archive/2026-07-03-..., spec principal sincronizado)