Recetor de webhooks fiável: assinatura, idempotência, fila e retentativas

Prompt

Atua como engenheiro backend com experiência em integrações e sistemas distribuídos.

Preciso de receber webhooks de forma fiável:
- Fornecedor e forma de assinatura: {{fornecedor}}
- Eventos que me interessam e o que faço com cada um: {{eventos}}
- Stack: {{stack}}
- Sistema de filas disponível: {{fila}}

Entregáveis:
1. Um diagrama em texto do fluxo: receção, verificação, persistência, colocação em fila, processamento, retentativas e fila de falhados.
2. O endpoint recetor:
   - Lê o corpo em bruto antes de o interpretar e verifica a assinatura HMAC com comparação em tempo constante.
   - Rejeita pedidos com marca temporal fora de uma janela curta, para evitar ataques de repetição.
   - Guarda o evento e responde 2xx em poucos milissegundos; nada de lógica pesada no pedido.
3. Idempotência: tabela de eventos com o id do fornecedor como chave única, estados (recebido, em processamento, concluído, falhado) e o que fazer se o mesmo evento chegar duas vezes.
4. Worker: processamento com backoff exponencial e jitter, limite de tentativas, distinção entre erros transitórios e permanentes, e fila de falhados com forma de os reprocessar.
5. Ordem de chegada: como tratar eventos fora de ordem (por exemplo, verificar a versão ou a data do recurso, ou voltar a consultá-lo na API do fornecedor).
6. Registos e alertas: o que registar sem guardar dados sensíveis e que métricas vigiar.
7. Testes: assinatura válida e inválida, evento duplicado, marca temporal antiga, falha transitória que recupera e falha permanente que acaba na fila de falhados.
8. Como testar em local (túnel ou reencaminhamento de eventos) sem expor o segredo.

Restrições:
- Não adivinhes o formato exato da assinatura nem os nomes dos cabeçalhos do fornecedor: se não os indicar, marca como [PREENCHER] e diz-me onde os consultar na documentação.
- O segredo é lido de variáveis de ambiente ou de um gestor de segredos, nunca do código.
- Se faltar informação essencial, pergunta-me antes de escrever código.

Como utilizar

Exemplo de utilização

Exemplo de resultado

Gateway → POST /webhooks/pagamentos → verificar assinatura + timestamp → INSERT evento (único)
        → commit → 200 → Celery: processar → retries com backoff → dead-letter

@router.post("/webhooks/pagamentos")
async def receber(request: Request, db: AsyncSession = Depends(get_db)) -> dict:
    bruto = await request.body()                      # corpo bruto, antes do parsing
    ts = request.headers.get("[COMPLETAR: cabeçalho de timestamp]", "")
    assinatura = request.headers.get("[COMPLETAR: cabeçalho de assinatura]", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        raise HTTPException(400, "timestamp em falta ou expirado")

    # Formato da mensagem assinada segundo a documentação do fornecedor: [COMPLETAR]
    esperada = hmac.new(settings.webhook_secret.encode(),
                        f"{ts}.".encode() + bruto, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperada, assinatura): # comparação em tempo constante
        raise HTTPException(400, "assinatura inválida")

    evento = json.loads(bruto)
    stmt = (insert(WebhookEvent)
            .values(provider_event_id=evento["id"], tipo=evento["type"],
                    payload=evento, estado="recebido")
            .on_conflict_do_nothing(index_elements=["provider_event_id"])
            .returning(WebhookEvent.id))
    novo_id = (await db.execute(stmt)).scalar_one_or_none()
    await db.commit()
    if novo_id is not None:                           # duplicado → não volta à fila
        processar_evento.delay(novo_id)
    return {"ok": True}

Dados-chave

Categoria

Programação e desenvolvimento · APIs

Tipo de resultado

Código

Nível

Avançado

Pensado para

ChatGPT, Claude, Gemini e Microsoft Copilot

Verificado em

Pendente de verificação editorial

Variáveis

Fornecedor e assinatura, Eventos e ações, Stack e Sistema de filas

Idioma

Português

Preço

Gratuito, sem registo

Atualizado

07/11/2026

Perguntas frequentes