Como funciona o recebimento

Os provedores com que o seu sistema conversa (gateway de pagamento, emissor de nota, GitHub) avisam de eventos mandando webhooks. Cada um assina de um jeito, retenta de um jeito e desiste de um jeito. O recebimento põe o Notyfacil no meio: o provedor manda para nós, nós conferimos a assinatura dele, guardamos a mensagem e a repassamos para você num formato só.

O caminho

Provedor → POST /in/{token} → assinatura conferida → Mensagem recebida → uma Entrega por destino → seu sistema

1. Você cria uma fonte e cola a URL de ingestão dela no painel do provedor.
2. O provedor manda o webhook para essa URL. A fonte confere a assinatura com o segredo que o provedor te deu e que você guardou nela.
3. A mensagem é gravada como chegou: método, headers e corpo, até 256 KB. Os headers de credencial são removidos antes de gravar.
4. Para cada destino habilitado da fonte sai uma Entrega, com o mesmo cronograma de retry, o mesmo histórico de tentativas e o mesmo replay do envio.

O que o seu sistema recebe

Uma verificação só. Todo repasse chega assinado com o secret do destino, nos headers Webhook-Id, Webhook-Timestamp e Webhook-Signature. O seu código verifica do mesmo jeito, venha do Mercado Pago ou do Stripe, e não precisa conhecer o esquema de assinatura de cada provedor: esse já foi conferido na entrada.

O corpo do provedor, sem envelope. O corpo sai exatamente como chegou, com o Content-Type original. O código que você já tinha para o formato do provedor continua servindo.

Um header a mais. Notyfacil-Source traz o id da fonte (src_…), para quando mais de uma fonte repassa para a mesma URL sua. Os headers originais do provedor não são repassados; eles ficam gravados na mensagem, para consulta.

O que o provedor vê

O contrato de resposta da URL de ingestão existe para não fazer o provedor desistir do webhook. Gateways desativam webhooks que falham demais, e o que te protege disso é responder 202 sempre que o problema não é do provedor.

Situação	Resposta
Aceita	202
Fonte pausada, ou quota do plano esgotada	202: a mensagem é gravada e não é repassada
Assinatura não confere	401: a tentativa é registrada, sem o corpo
Token desconhecido	404
Corpo acima de 256 KB	413
Limite de requisições	429, com Retry-After
O provedor exige segredo e a fonte não tem	503

Um detalhe que decorre disso: o seu servidor fora do ar não aparece para o provedor. Ele recebe 202, e quem segura o retry até o seu sistema voltar somos nós.

Por que passar pelo meio

• Histórico de tudo que chegou, inclusive o que a verificação recusou, com replay a qualquer momento.
• Queda sua não custa o webhook do provedor, pelo motivo acima.
• Alerta de silêncio. A fonte avisa por e-mail quando passa tempo demais sem receber nada. É assim que se descobre que o provedor desativou o webhook antes de um cliente reclamar de um pagamento que não foi processado. Veja fontes.