¿Webhooks o polling? Un seguimiento de pedidos que puede recuperarse

Usa webhooks para los cambios habituales y conserva consultas de estado para comprobar que tus registros coinciden con el panel. Si aún no tienes un receptor público fiable, empieza con polling por lotes.

Un pedido puede finalizar durante un reinicio y un evento puede llegar dos veces si se pierde su confirmación. El seguimiento debe resolver ambos casos sin mostrar información antigua ni aplicar dos veces la misma actualización.

Una función para cada método

Polling: consultar el estado actual

action=status devuelve el estado en ese momento. Puedes agrupar hasta 100 IDs. Consultar más a menudo genera más solicitudes, incluso cuando nada cambia.

Webhooks: recibir cambios seleccionados

NotPanel envía eventos a tu URL HTTPS. No consumen la cuota de solicitudes status de tu cliente, pero tu receptor necesita capacidad y supervisión.

Conciliación: recuperar lo que falta

Tras una interrupción o ante un registro antiguo, consulta los pedidos afectados. Un evento puede perderse; los reintentos son limitados y la entrega no está garantizada.

Qué envía la API de NotPanel

Añade un endpoint en la página API de tu dashboard o con webhook.add: una URL HTTPS pública y los eventos que necesites, como order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed y refill.rejected; la referencia de webhooks los enumera todos. Guarda el secreto: se muestra una sola vez y webhook.list nunca lo devuelve. Consulta tus endpoints con webhook.list, envía un ping de prueba con webhook.test y elimina un endpoint con webhook.remove.

Cada entrega lleva un solo evento en un sobre breve: id, type, schema_version, created_at, sequence y data. data.order tiene los mismos campos que una respuesta de action=status. El ejemplo abreviado muestra la forma, no un pedido real.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Lee el tipo de evento del cuerpo verificado. También se envía X-Webhook-Event, pero no está firmado. Los endpoints creados en el dashboard y por la API reciben el mismo formato.

Recibir eventos de forma segura

1. Conserva el cuerpo original. Verifica X-Webhook-Signature con el secreto y X-Webhook-Timestamp; aplica tu tolerancia temporal. Reconstruir el contenido puede alterar los bytes firmados.
2. Registra X-Webhook-Delivery-Id para seguir los intentos; es el mismo en cada reintento de esa entrega. Guarda el evento verificado antes de devolver 2xx; si no puedes aceptarlo con seguridad, permite el reintento.
3. Procesa cada id de evento una vez, conservando esa información tras reinicios junto con la actualización del pedido. El mismo id de evento llega a cada endpoint suscrito a él.
4. Haz el trabajo lento después de aceptar. La firma confirma autenticidad, no orden de llegada. Usa sequence para ordenar los eventos y, si uno tardío contradice el estado reciente, consulta status antes de sustituirlo.

Guía de verificación de firmas

Cuando tu receptor no está disponible

Un timeout (10 segundos) o una respuesta no 2xx es un intento fallido. NotPanel intenta cada entrega hasta 8 veces en 24 horas: al momento y luego 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas después del evento. Pausa el endpoint tras 50 fallos seguidos o 3 días sin un éxito, y avisa al titular de la cuenta. Una entrega correcta reinicia el contador. Revisa webhook.list: el silencio no demuestra ausencia de cambios.

Comprueba periódicamente pedidos pendientes o antiguos en lotes de hasta 100 IDs, respetando cabeceras y límites. Tras reparar el receptor, reanuda el endpoint en la sección de webhooks de la página API de tu dashboard; así se borra su contador de fallos. También puedes eliminarlo con webhook.remove, añadir de nuevo la URL HTTPS reparada con webhook.add y los eventos deseados, guardar el nuevo secreto de forma segura y actualizar el receptor para verificar con él. La API pública no ofrece una acción para reanudar un endpoint. Las entregas pendientes al pausarse no se reenvían, así que concilia los estados omitidos con status.

Prueba más que una entrega correcta

Usa mensajes sintéticos y un secreto de pruebas propio; no necesitas pedidos reales.

• La misma entrega dos veces debe generar una actualización.
• El mismo evento entregado dos veces con un reinicio en medio debe reconocerse como ya procesado.
• Un byte modificado o fecha antigua debe fallar según tu política.
• Tras una interrupción y un evento tardío, status debe recuperar la vista actual.

Seleccionar eventos, verificar secretos y confirmar pronto también forma parte de las recomendaciones de GitHub. Las cabeceras, los formatos y los límites descritos aquí corresponden a NotPanel.

Preguntas frecuentes

¿Puedo usar solo polling?

Sí. Agrupa consultas y adapta su frecuencia al volumen y los límites. Los webhooks no son obligatorios para crear o seguir pedidos.

¿Los webhooks llegan inmediatamente y una sola vez?

No. Pueden retrasarse o repetirse. Verifica cada entrega, procesa cada evento una vez y conserva consultas de estado para recuperar información.

¿Qué cabeceras debo comprobar?

X-Webhook-Signature y X-Webhook-Timestamp; después lee id, type y data del cuerpo verificado. Usa X-Webhook-Delivery-Id solo para seguir los intentos.

¿El webhook protege un add incierto?

Son problemas distintos. Reintenta el add con su request_id original y parámetros sin cambios; guarda el ID de pedido recuperado.

Referencias: contrato de webhooks · estado del pedido · recuperación tras timeout.