Buscar na documentação

Módulos

Authentication

Merchant

Catalog

Order

Events

Logistics

Shipping

Review

Financial

Soluções

Events

Presença no webhook

O webhook usa heartbeats para indicar presença. O iFood envia requests periódicas para verificar se sua integração está online e quais merchants estão ativos.Como funciona:

Webhook habilitado → heartbeats começam em até 30 segundos
iFood envia request KEEPALIVE
Você responde indicando quais merchants estão online
iFood atualiza status de presença

Saiba mais sobre o conceito de presença e como ele afeta a visibilidade de merchants.

Modos de operação

Por aplicativo (todos os merchants online)

Use quando não precisar controlar presença individualmente. Uma única resposta 202 Accepted marca todos os merchants com escopo order como online.Request do iFood:

{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e"
}

Como responder:

HTTP/1.1 202 Accepted

202 Accepted → todos os merchants ficam online
Qualquer outro código → nenhum merchant fica online
Response body é ignorado

Resultado

Todos os merchants com escopo order aparecem como disponíveis na plataforma, desde que atendam aos outros critérios (horário de funcionamento, configurações, etc.).

Exemplo de request

curl -X POST 'http://localhost:8080/webhook' \
  -H 'X-IFood-Signature: 6c0a429606266905349388ebc1eb12b8b98524dddd6b4bdc41c4b67591075b4c' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e"
  }'

Por merchant (controle individualizado)Use quando precisar controlar presença de cada merchant separadamente. O iFood envia lista de até 1000 merchants por request. Você responde com a lista dos que estão online.

Request do iFood

{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e",
    "merchantIds": [
        "cad65e8f-6fc6-438a-b159-e64a902a6b9a",
        "438a5e8f-6fc6-438a-b159-e64a902a6879"
    ]
}

Como responder

HTTP/1.1 202 Accepted
Content-Type: application/json

{
   "merchantIds": ["cad65e8f-6fc6-438a-b159-e64a902a6b9a"]
}

Retorne apenas os IDs dos merchants online
Merchants não incluídos na resposta ficam offline
Resposta deve ser 202 Accepted + JSON com merchantIds

Exemplo de request

curl -X POST 'http://localhost:8080/webhook' \
  -H 'X-IFood-Signature: dc900bca38c8b6f908ea688a24604fa581921d1211da4211e4f5e139732c2ff1' \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "KEEPALIVE",
    "fullCode": "KEEPALIVE",
    "id": "a38ba215-f949-4b2c-982a-0582a9d0c10e",
    "merchantIds": ["cad65e8f-6fc6-438a-b159-e64a902a6b9a", "438a5e8f-6fc6-438a-b159-e64a902a6879"]
  }'

Compatibilidade: Resquests de presença seguem a mesma estrutura de eventos de pedido, facilitando o processamento no mesmo endpoint.

Configuração

Configure o modo de presença na aba do Developer Portal:

Por aplicativo (padrão): Um heartbeat para todos os merchants
Por merchant: Heartbeats com lista de merchants, resposta com IDs online

Veja aqui como configurar o webhook.

Validação de assinatura

Hearbeats incluem o header X-IFood-Signature como qualquer outro evento. Valide antes de processar. Veja aqui como validar assinatura.

Casos de uso

Caso 1: Sistema sempre online

Cenário: Seu sistema está sempre disponível e todos os merchants devem ficar online.Solução: Use o modo "por aplicativo" e sempre responda 202 Accepted.

Caso 2: Merchants com horários diferentes

Cenário: Alguns merchants fecham à noite, outros ficam 24h.Solução: Use o modo "por merchant" e filtre por horário de funcionamento antes de responder.

@app.route('/webhook', methods=['POST'])
def webhook():
    event = request.json
    
    if event['code'] == 'KEEPALIVE':
        if 'merchantIds' in event:
            # Modo por merchant
            online_merchants = [
                m for m in event['merchantIds']
                if is_open(m)  # Verifica horário
            ]
            return jsonify({'merchantIds': online_merchants}), 202
        else:
            # Modo por aplicativo
            return '', 202
    
    # ... processar outros eventos

Caso 3: Sistema em manutenção

Cenário: Sistema offline por manutenção. Solução:

Modo por aplicativo: Responda 503 Service Unavailable → todos os merchants ficam offline
Modo por merchant: Responda 202 com lista vazia {"merchantIds": []}

FAQ

Consulte nossa FAQ sobre presença no webhook.

Esta página foi útil?

Avalie sua experiência no novo Developer portal:

Nesta página