Visão geral

O webhook é um mecanismo de entrega de eventos server-server em tempo real. É a solução recomendada em situações onde a integradora tem acesso a vários merchants e faz o gerenciamento dos pedidos de forma centralizada. Com isso podemos evitar a limitação de múltiplos pollings para integrações com muitos merchants.

Polling vs Webhook

Webhooks são uma alternativa ao desperdício do polling contínuo. O exemplo a seguir usa os eventos requests/create webhook para ilustrar a diferença:

O aplicativo especifica um endpoint HTTPS hospedado pelo servidor da integradora para receber eventos do webhook.

Conceitos do webhook

As definições a seguir explicam os conceitos relacionados com o webhook:

• Evento: uma mensagem de evento único. Para ler mais sobre eventos de pedidos do iFood:

• Assinatura da request: um header contendo uma string de validação do webhook. Por ser um conceito importante, temos uma página dedicada ao assunto:

• Request: o iFood faz ao menos uma request HTTP para cada evento para cada aplicativo com cadastro no webhook que deva receber aquele evento. A request é composta pelo body, 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:

Testando o webhook

A aba de configuração do webhook no developer portal tem um botão para testar a conexão do webhook. Esse botão gera um mock de request de presença para o webhook cadastrado. Essa request não é real, no sentido de que ela não é feita pelo serviço de webhook e por tanto não gera um heartbeat. Esse botão tem o único propósito de auxiliar a integração a simular uma request para o endpoint cadastrado.

Além disso, o developer portal tem a ferramenta para gerar pedidos de teste, que no fim acaba gerando e entregando um evento de PLACED via polling e webhook.

Resiliência

Hoje tentamos entregar eventos de um pedido por até 15 minutos após a primeira tentativa de entrega. Se todas as tentativas de entrega falharem, o evento é descartado. O iFood reserva o direito de alterar o número de tentativas, tempo entre as tentativas e o tempo máximo para as tentativas (avisando possíveis reduções de tempo máximo para a última tentativa).

Notificações de Webhook com Erros

Os aplicativos integrados com o método de entrega de eventos por Webhook podem ser notificados caso sejam detectados erros na entrega dos eventos.

O webhook recebe um evento por requisição e, caso essas requisições falhem, seja por indisponibilidade, timeout, ou resposta de erro, nosso sistema irá enviar uma notificação automática, no email cadastrado para o aplicativo, avisando sobre os erros encontrados.

Existem alguns cenários de notificações que irão ser considerados, dado os níveis de criticidade de cada alerta detectado.

• Falha de Healthcheck: Quando a verificação de healthcheck, que está atrelada ao [mecanismo de presença](/docs/guides/order/events/delivery-methods/webhook/presence), apresentar erros, enviaremos uma notificação avisando sobre o problema e de suas consequências (uma vez por dia, enquanto o problema persistir), uma ação imediata é esperada nesse caso, dado sua gravidade.
• Alerta de Erro: Quando uma quantidade pequena de erros é detectada dentro de uma determinada janela de tempo. Será enviada uma notificação (uma vez por dia, enquanto o problema persistir) para que fiquem cientes sobre o problema.
• Alerta de Erro Crítico: Quando uma quantidade muito alta de erros é detectada, dentro de uma determinada janela de tempo. Será enviada uma notificação (com reenvio a cada 4 horas, enquanto o problema persistir), avisando sobre a gravidade do problema e que uma ação imediata deve ser tomada.
• Alerta de Webhook Desabilitado: Quando detectamos um caso de Alerta de Erro Crítico não solucionado dentro de uma janela de 72 horas, desabilitaremos o Webhook automaticamente e enviaremos uma notificação sobre o ocorrido.

Limitações

• Cada aplicativo cadastrado no portal do iFood pode ter no máximo uma URL de webhook cadastrada de até 250 caracteres

• A ordem de entrega dos eventos não é garantida. Por exemplo, é teoricamente possível que um evento de confirmação seja entregue antes do evento de criação (apesar de improvável). Isso se dá pois no webhook cada evento depende do tempo de processamento de cada app, então se uma app processar um pedido e imediatamente confirmar o pedido, é teoricamente possível que outra app receba a confirmação sem ainda ter criado o pedido;

• O webhook garante a entrega "at least once". Isso significa que um endpoint pode receber o mesmo evento de webhook mais de uma vez. Você pode detectar eventos duplicados pelo campo id na mensagem enviada pelo webhook;

• Hoje o webhook é capaz de entregar diferentes tipos de eventos em um mesmo endpoint, mas sem possibilidade de filtros por tipo de evento ou merchant como no polling; ficando sob responsabilidade da integradora selecionar os eventos que quiser tratar.

• Diferente do polling, o webhook não possui um mecanismo de acknowledgment, e embora tenha um mecanismo de retry, caso o envio falhe um número predeterminado de vezes definido pelo iFood, um evento pode ser descartado sem ser recebido pela integradora. Hoje não é possível recuperar estes eventos de forma automática, sendo necessário recorrer ao mecanismo de polling como fallback caso a integradora venha a ter alguma instabilidade por um período longo de tempo;

• Hoje o polling e o webhook são sistemas totalmente independentes para entrega de eventos. Caso tenha interesse em utilizar o polling como fallback ou sistema de conciliação, é necessário enviar requests de acknowledgment para o sistema de polling. No caso do polling como fallback, recomendamos fazer o polling a cada 5 minutos. O que irá acontecer é que a maioria das requests de polling devem vir vazias (ainda devem vir poucos eventos no polling por questão de concorrência);

Critérios de homologação

• Receber eventos via webhook de eventos do iFood com sucesso.
• Responder com falha a eventos com assinatura inválida.

Referências

Configurando o Webhook

Request feita pelo Webhook

Assinatura das requests do Webhook

Eventos de Pedidos

Presença no iFood

Presença no Webhook

Boas práticas no Webhook

FAQ Webhook