Visão geral
O webhook entrega eventos server-to-server em tempo real. Recomendamos seu uso quando a integradora gerencia vários merchants e centraliza os pedidos. Esse método evita as limitações do polling em integrações com muitos merchants.O webhook só está disponível para aplicativos com autenticação centralizada.
Polling vs Webhook
Webhooks evitam o uso de polling contínuo. O exemplo abaixo mostra como o evento requests/create usa webhooks para notificar em vez de consultar.
O aplicativo especifica um endpoint HTTPS hospedado pelo servidor da integradora para receber eventos do webhook.Conceitos do webhook
As definições a seguir detalham os principais conceitos do webhook.Evento
Uma mensagem de evento únicoAssinatura da request
Um header contendo uma string de validação do webhookRequest do webhook
O iFood envia pelo menos uma requisição HTTP para cada evento a cada aplicativo cadastrado no webhook. A requisição inclui o corpo da mensagem, o header de assinatura e possíveis metadados nos cabeçalhos.- Presença: presença, ou status de conexão está relacionado com o conceito de aberto/fechado de lojas no aplicativo do iFood. Para se aprofundar no assunto:
Presença no webhook
Presença representa o status de conexão indica se a loja está aberta ou fechada no aplicativo do iFoodTestando o webhook
A aba de configuração do webhook no Developer Portal inclui um botão para testar a conexão. Esse botão envia um mock de request de presença para o endpoint cadastrado. A request não é gerada pelo serviço real de webhook e não produz um heartbeat. Use esse recurso apenas para simular uma request e validar a integração.O Developer Portal também oferece uma ferramenta para gerar pedidos de teste. Ela cria eventosPLACED entregues por pooling e webhook. Resiliência
O iFood tenta entregar eventos de um pedido por até 15 minutos após a primeira tentativa. Se todas as tentativas falharem, o evento é descartado. O iFood pode ajustar o número de tentativas, o intervalo entre elas e o tempo máximo de entrega. Notificaremos sobre possíveis reduções no prazo da última tentativa.Notificações de erro no webhook
Aplicativos integrados por webhook recebem notificações de erro quando falhas de entrega ocorrem. Cada evento é enviado em uma requisição separada. Se uma entrega falhar por indisponibilidade, timeout ou erro, o sistema envia uma notificação automática para o e-mail cadastrado do aplicativo.O tipo de notificação varia conforme a criticidade do erro detectado.- Falha de healthcheck: Se a verificação de healthcheck, vinculada ao [mecanismo de presença](/docs/guides/order/events/delivery-methods/webhook/presence), apresentar erro, enviamos uma notificação diária enquanto o problema persistir. Esperamos ação imediata devido à gravidade.
- Alerta de Erro: Notificamos uma vez por dia quando detectamos poucos erros em um mesmo período, até que o problema seja resolvido.
- Alerta de Erro Crítico: Se o número de erros for muito alto em um período, enviamos notificações a cada 4 horas até a resolução. Ação imediata é necessária.
- Webhook desabilitado: Se um erro crítico não for resolvido em 72 horas, desabilitamos o webhook e notificamos sobre a ação.
Limitações
- Cada aplicativo pode cadastrar uma única URL de webhook, com até 250 caracteres.
- O webhook não garante a ordem de entrega dos eventos. Por diferenças no tempo de processamento, você pode receber uma confirmação antes da criação do pedido, mesmo que isso seja raro.
- O webhook garante a entrega "at least once". Um endpoint pode receber o mesmo evento mais de uma vez. Use o campo
idpara identificar duplicidades. - O webhook entrega diferentes tipos de eventos no mesmo endpoint. Não oferece filtros por tipo de evento ou merchant, como no polling. A integradora deve selecionar os eventos que deseja tratar.
- O webhook não possui mecanismo de acknowledgment. Mesmo com tentativas de reenvio, o sistema pode descartar eventos após várias falhas de entrega. Não é possível recuperar esses eventos automaticamente. Use o polling como fallback em casos de instabilidade prolongada.
- O polling e o webhook funcionam de forma independente. Para usar o polling como fallback ou conciliação, envie requests de acknowledgment ao sistema de polling. Recomendamos polling a cada 5 minutos. A maioria das requests deve retornar vazia, pois o webhook já terá entregue os eventos.
Critérios de homologação
- Receber eventos via webhook de eventos do iFood com sucesso.
- Responder com falha a eventos com assinatura inválida.