Boas práticas

1. Responda rapidamente

• Use fila (SQS, RabbitMQ, Kafka) para armazenar evento
• Processe assíncronamente
• Não faça validações pesadas ou chamadas externas antes de responder

# ❌ Evite
@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json
    validate_signature(request.headers['X-IFood-Signature'], request.data)
    process_order(event)  # Pode demorar > 5s
    return '', 202

# ✅ Recomendado
@app.route('/webhook', methods=['POST'])
def webhook():
    validate_signature(request.headers['X-IFood-Signature'], request.data)
    queue.push(request.data)  # Rápido
    return '', 202

2. Valide assinatura antes de processar

Cuidados

• Não faça parse do JSON antes de validar
• Não normalize espaços ou quebras de linha
• Não reordene propriedades

3. Implemente idempotência

Solução

• Use o campo id do evento como chave única
• Armazene IDs processados (cache, banco)
• Ignore eventos duplicados

processed_events = set()  # ou Redis, DB

if event['id'] in processed_events:
    return '', 202  # Já processado

processed_events.add(event['id'])
# ... processar evento

4. Gerencia atrasos

Solução

• Compare o createdAt do evento com a hora atual
• Se o atraso for > threshold (ex: 10min), valide o estado atual do pedido
• Use pooling para reconciliação

5. Monitore falhas

• Taxa de sucesso (201 vs 5xx)
• Latência de resposta (p50, p95, p99)
• Eventos duplicados
• Eventos descartados (via suporte)

Ferramentas

• Logs estruturados (JSON)
• Alertas para taxa de erro > 5%
• Dashboards (Datadog, Grafana)

6 Use polling como fallback

Recomendação

• Polling a cada 30 min (baixa frequência)
• Ou ative quando detectar problema no webhook
• Eventos disponíveis por 8h

7. Permita IPs do iFood no firewall

34.202.11.230
34.228.183.194
44.207.41.97
44.208.105.236
54.85.55.192

Troubleshooting

Problema: Assinatura inválida

• Erro de validação HMAC
• Eventos rejeitados constantemente

1. Parse antes de validar

• Bibliotecas de web framework transformam JSON antes de você acessar o body
• Solução: Acesse o byte array bruto (request.data no Flask, req.body no Express)

2. Formação diferente

• JSON {"a":1,"b":2} vs {"b":2,"a":1} são equivalentes, mas têm assinaturas diferentes
• Solução: Valide byte array exatamente como recebido

3. Client secret errado

• Verifique se está usando o secret correto no Developer Portal

# Teste com curl (secret: "dummysecret")
curl -X POST http://localhost:8080/webhook \
  -H 'X-IFood-Signature: 6f9ed23a7b505a3b6907c5f6eb2ad1b056fbf35a643d365a9a072ed7aabca153' \
  -H 'Content-Type: application/json' \
  -d '{"code":"PLC","id":"123"}'

Problema: Eventos duplicados

• Mesmo id recebido múltiplas vezes

1. Timeouts

• Você responde após 5s → iFood reenvia
• Solução: Responda em < 2s, processe depois

2. Falta de idempotência

• Solução: Use o campo id para deduplicar

Problema: Não recebo requests

1. Firewall bloqueando IPs

• Solução: Libere os IPs do iFood. Confira a lista [aqui](## 7. Permita IPs do iFood no firewall)

2. Webhook desabilitado

• Verifique status no Developer Portal
• Pode ter sido bloqueado por erros críticos

3. URL incorreta

• Verifique se a URL está acessível externamente
• Teste com curl de fora da sua rede

Problema: Timeouts

• Eventos reenviados mesmo respondendo 202
• Logs mostram requests > 5s

• Use fila assíncrona
• Responsa imediatamente
• Processe depois

# Flask detecta request cancelada
from flask import request

@app.route('/webhook', methods=['POST'])
def webhook():
    if request.environ.get('wsgi.input_terminated'):
        # Request foi cancelada
        pass

Problema: Cache no API Gateway

• Primeira request falha
• Requests subsequentes falham com o mesmo erro

• Desabilite cache para endpoint de webhook
• Configure API Gateway para não cachear POSTs

Ferramenta de debug (iFood)

• Entrada do evento na plataforma
• Tentativas de entrega
• Códigos de resposta
• Eventos descartados

• Abra ticket no suporte
• Inclua: id do evento, timestamp, logs do seu servidor
• Está no roadmap externalizar essa ferramenta

Checklist de troubleshooting

• Assinatura validada corretamente (byte array bruto)
• Resposta em < 5 segundos
• IPs do iFood liberados no firewall
• Idempotência implementada (campo id)
• Logs estruturados habilitados
• Webhook habilitado no Developer Portal
• URL acessível externamente (teste com curl)