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é 3 MB. 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 notyfacil-id, notyfacil-timestamp e notyfacil-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 200 sempre que o problema não é do provedor.

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

A Meta confirma a URL antes de começar a entregar. Ao salvar a callback no App, ela chama a URL de ingestão com GET, e a fonte devolve o hub.challenge quando o hub.verify_token é o Verify token da fonte. O Verify token aparece no painel ao lado da URL, e em verifyToken na fonte. Esse GET funciona antes de a App Secret estar configurada e não grava mensagem.

Um detalhe que decorre disso: o seu servidor fora do ar não aparece para o provedor. Ele recebe 200, 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.