Visão geral

O MuPag entrega eventos ao endpoint HTTPS do lojista com POST e Content-Type: application/json. O corpo é o envelope {"id","type","data"}. Não há User-Agent. A conexão não segue redirecionamento: um 3xx volta como resposta não-2xx e a entrega é abandonada.

Onde nasce o segredo

O OpenAPI de chave de API não cadastra endpoints. O segredo nasce no dashboard de QA, na seção Webhooks do lojista. A criação mostra secret uma única vez, no formato whsec_ seguido do token. A rotação também mostra o segredo novo uma única vez. A listagem não inclui o segredo. Tokens sk_* e pk_* não servem para esse cadastro.

A URL precisa ser HTTPS pública, sem userinfo e sem host privado, localhost, sufixo .local, link-local ou ULA. No cadastro, o emissor envia o ping com o corpo exato {"id":"webhook.test","type":"webhook.test","data":{"ping":true}}. Status 2xx marca o endpoint como verified. Qualquer outro resultado deixa pending_verification. O endpoint e o segredo permanecem nos dois casos. webhook.test é só esse ping; não é um evento Kafka.

Cabeçalhos da entrega

• MuPag-Signature: t=<epoch em segundos>,v1=<HMAC-SHA256 em hex minúsculo de 64 caracteres>
• X-Gateway-Signature: alias temporário com o mesmo valor de MuPag-Signature
• X-Gateway-Event-Id: igual ao id do corpo
• X-Gateway-Timestamp: o mesmo epoch usado na assinatura
• Accept: */*
• Connection: close
• Host: hostname original

Cada tentativa aplica 10 segundos ao connect TCP e a cada leitura do socket. Não é um prazo total da tentativa: um corpo enviado devagar pode ultrapassar 10 segundos. Sucesso é qualquer status de 200 a 299.

O que fazer ao receber

1. Guarde o corpo cru, sem reformatar o JSON.
2. Valide MuPag-Signature como em Assinatura.
3. Deduplique pelo id.
4. Persista o efeito e só então responda 2xx.

O emissor não impõe janela de tolerância. A função verify recebe a tolerância de quem chama, e os testes unitários usam 300 segundos. A entrega de produção não chama verify e não fixa esse número.

Eventos com contrato inválido ou corpo acima de 65536 bytes UTF-8 vão para quarentena interna e não são entregues. Não há API pública de dead letter.

Os detalhes de repetição estão em Retries. Os tipos assinados estão em Catálogo de eventos. A deduplicação está em Segurança contra replay.