Receber os eventos de Pix Automático

Resposta rápida: Registre PUT /webhookrec e PUT /webhookcobr — são de conta, sem chave no path, e independentes do webhook da cobrança imediata; mapeie APROVADA/CANCELADA/EXPIRADA do mandato e ATIVA/CONCLUÍDA/REJEITADA do ciclo, confirmando por GET antes de mudar o estado da assinatura.

Por que isto não briga com o webhook de cob

O webhook da cobrança imediata é registrado por chave Pix (PUT /webhook/{chave}). Os dois da recorrência são da conta e não levam chave no caminho. Registrar a recorrência não altera a URL de callback do cob.

Consequência prática: uma conta pode servir um produto que só usa cob e outro que só usa recorrência, cada um com sua URL, sem proxy no meio. Dois produtos na mesma modalidade, aí sim, disputam a mesma URL.

Passo a passo

1. Registre as duas URLs (snippet abaixo) e leia de volta com GET — é a única prova do que ficou gravado.
2. Trate o webhook como aviso, não como verdade: confirme com GET /rec/{idRec} ou GET /cobr/{txid} antes de mudar o estado do assinante.
3. Proteja o endpoint por secret (query ou header). Não existe assinatura — mesma regra da cobrança imediata.
4. Idempotência por idRec (mandato) e por txid (ciclo): entrega repetida é esperada.
5. Espere eventos em lote: EXPIRADA não chega no instante do vencimento — costuma vir em varredura horária.

Mapa de eventos

webhookrec — o mandato:

Evento	Significado	Efeito típico na assinatura
APROVADA / CONFIRMADA	Pagador aceitou; a partir daqui pode enviar cobr	Liberar acesso (ou aguardar o primeiro ciclo pago, conforme sua regra)
REJEITADA	Pagador recusou a autorização	Não promover; oferecer outro meio
CANCELADA	Pagador cancelou depois de ter aprovado	Encerrar no fim do ciclo pago
EXPIRADA	Fim da recorrência ou prazo de autorização vencido	Encerrar; chega em lote horário

webhookcobr — cada ciclo:

Evento	Significado	Efeito típico
ATIVA	Aceita e agendada pelo PSP do pagador	Nada ainda: agendado não é pago
CONCLUÍDA	Ciclo pago	Estender o acesso
REJEITADA	PSP do pagador recusou	Inadimplência; retentativa se a política permitir
CANCELADA (pagador)	Pagador cancelou a cobrança	Inadimplência
CANCELADA (recebedor)	Você cancelou	Nada — foi ação sua

Duas armadilhas de mapeamento que valem código explícito: ATIVA não é pagamento (é agendamento), e APROVADA não é receita (é permissão para cobrar).

Código

Fonte canônica: snippets/curl/register-webhookrec.sh.

# source: snippets/curl/register-webhookrec.sh
for WH in webhookrec webhookcobr; do
  curl -sS -X PUT "{{MODOBANK_API_BASE}}/$WH" \
    --cert '{{PATH_TO_CERT}}' --key '{{PATH_TO_KEY}}' --cacert '{{PATH_TO_CA}}' \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
    -H 'Content-Type: application/json' \
    -d '{"webhookUrl":"{{WEBHOOK_URL}}"}' \
    -o /dev/null -w "$WH PUT=%{http_code}\n"

  curl -sS "{{MODOBANK_API_BASE}}/$WH" \
    --cert '{{PATH_TO_CERT}}' --key '{{PATH_TO_KEY}}' --cacert '{{PATH_TO_CA}}' \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
    -w "\n$WH GET=%{http_code}\n"
done

Remoção, quando precisar: DELETE /webhookrec e DELETE /webhookcobr.

Se der errado

Sintoma	Causa	Ação
403 no PUT	Credencial sem webhookrec.write / webhookcobr.write	Pedir escopo ao banco
Webhook de cob parou depois de mexer na recorrência	Provavelmente não é isso — os registros são independentes	Conferir GET /webhook/{chave} antes de culpar a mudança
Assinatura liberada e ninguém pagou	ATIVA tratada como pagamento	Liberar só em CONCLUÍDA
Assinatura cai sozinha no dia do vencimento	Espera de EXPIRADA em tempo real	Lembrar do lote horário; não expirar por conta própria antes disso
Estado muda com body forjado	Confiança no webhook	Confirmar com GET antes de aplicar

Checklist

• webhookrec e webhookcobr registrados e lidos de volta
• Webhook de cob conferido depois do registro (deve estar intacto)
• Secret validado (errado → 401, certo → 200)
• ATIVA não libera acesso
• Confirmação por GET antes de qualquer mudança de estado
• Idempotência testada com entrega repetida

FAQ

P: Dá para usar a mesma URL dos dois webhooks?

R: Sim. O corpo diz de qual recurso o evento é; separar por rota é só conveniência.

P: E se o cliente quiser cancelar comigo, e não no banco?

R: O cancelamento do mandato é no banco do pagador. Do seu lado, o que existe é cancelar cobranças de ciclo.