Visión general

El webhook entrega eventos server-to-server en tiempo real. Recomendamos su uso cuando la integradora gestiona varios merchants y centraliza los pedidos. Este método evita las limitaciones del polling en integraciones con muchos merchants.

El webhook solo está disponible para aplicaciones con autenticación centralizada.

Polling vs Webhook

Los webhooks evitan el uso de polling continuo. El ejemplo abajo muestra cómo el evento requests/create usa webhooks para notificar en vez de consultar.

La aplicación especifica un endpoint HTTPS hospedado por el servidor de la integradora para recibir eventos del webhook.

Conceptos del webhook

Las definiciones a continuación detallan los principales conceptos del webhook.

Evento

Un mensaje de evento único

Firma de la request

Un header conteniendo una string de validación del webhook

Request del webhook

iFood envía al menos una solicitud HTTP para cada evento a cada aplicación registrada en el webhook. La solicitud incluye el cuerpo del mensaje, el header de firma y posibles metadatos en los headers.

Presencia en el webhook

La presencia representa el estado de conexión que indica si la tienda está abierta o cerrada en la aplicación de iFood

Probando el webhook

La pestaña de configuración del webhook en el Developer Portal incluye un botón para probar la conexión. Ese botón envía un mock de request de presencia al endpoint registrado. La request no es generada por el servicio real de webhook y no produce un heartbeat. Usa este recurso solo para simular una request y validar la integración.El Developer Portal también ofrece una herramienta para generar pedidos de prueba. Esta crea eventos PLACED entregados por polling y webhook.

Resistencia

iFood intenta entregar eventos de un pedido por hasta 15 minutos después del primer intento. Si todos los intentos fallan, el evento es descartado. iFood puede ajustar el número de intentos, el intervalo entre ellos y el tiempo máximo de entrega. Notificaremos sobre posibles reducciones en el plazo del último intento.

Notificaciones de error

Las aplicaciones integradas por webhook reciben notificaciones de error cuando ocurren fallos de entrega. Cada evento es enviado en una solicitud separada. Si una entrega falla por indisponibilidad, timeout o error, el sistema envía una notificación automática al email registrado de la aplicación.El tipo de notificación varía conforme a la criticidad del error detectado.

Falla de healthcheck: Si la verificación de healthcheck, vinculada al [concepto de presencia](/docs/guides/modules/events/webhook-presence), presenta error, enviamos una notificación diaria mientras el problema persista. Esperamos acción inmediata debido a la gravedad.
Alerta de Error: Notificamos una vez por día cuando detectamos pocos errores en un mismo período, hasta que el problema sea resuelto.
Alerta de Error Crítico: Si el número de errores es muy alto en un período, enviamos notificaciones cada 4 horas hasta la resolución. Acción inmediata es necesaria.
Webhook deshabilitado: Si un error crítico no se resuelve en 72 horas, deshabilitamos el webhook y notificamos sobre la acción.

Limitaciones

Cada aplicación puede registrar una única URL de webhook, con hasta 250 caracteres.
El webhook no garantiza el orden de entrega de los eventos. Por diferencias en el tiempo de procesamiento, puedes recibir una confirmación antes de la creación del pedido, aunque esto sea raro.
El webhook garantiza la entrega "at least once". Un endpoint puede recibir el mismo evento más de una vez. Usa el campo id para identificar duplicidades.
El webhook entrega diferentes tipos de eventos en el mismo endpoint. No ofrece filtros por tipo de evento o merchant, como en el polling. La integradora debe seleccionar los eventos que desea tratar.
El webhook no posee mecanismo de acknowledgment. Aun con intentos de reenvío, el sistema puede descartar eventos después de varios fallos de entrega. No es posible recuperar esos eventos automáticamente. Usa el polling como fallback en casos de inestabilidad prolongada.
El polling y el webhook funcionan de forma independiente. Para usar el polling como fallback o conciliación, envía requests de acknowledgment al sistema de polling. Recomendamos polling cada 5 minutos. La mayoría de las requests debe retornar vacía, pues el webhook ya habrá entregado los eventos.