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
Esta guía cubre registros con webhook.add: una URL HTTPS pública y eventos compatibles, como order.processing, order.in_progress, order.completed, order.partial, order.refunded y order.refill_completed. Guarda el secreto; webhook.list no lo devuelve. Consulta estado y fallos con webhook.list y elimina registros con webhook.remove.
Las entregas API contienen events, incluso con un solo evento. Cada elemento tiene id, event, timestamp y data; deliveryId identifica la entrega. El ejemplo abreviado es ilustrativo. Sus fechas antiguas no sirven para probar la tolerancia temporal.
{
"events": [
{
"id": "EXAMPLE_EVENT_ID",
"event": "order.completed",
"timestamp": 1700000000,
"data": { "order": 7001, "status_key": "completed" }
}
],
"timestamp": 1700000001,
"deliveryId": "EXAMPLE_DELIVERY_ID"
}Lee el evento del cuerpo verificado: los lotes API no requieren X-Webhook-Event. Los webhooks creados en el dashboard usan otro formato de evento único; no intercambies ambos formatos.
Verifica la firma sobre el cuerpo original y comprueba su marca temporal.
Guarda la entrega verificada antes de responder con 2xx.
Aplica cada evento una vez y recupera información con consultas de estado.
Recibir eventos de forma segura
- 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.
- Comprueba que X-Webhook-Delivery-Id coincide con deliveryId del cuerpo firmado. Guarda la entrega antes de devolver 2xx; si no puedes aceptarla con seguridad, permite el reintento.
- Procesa cada events[].id una vez, conservando esa información tras reinicios junto con la actualización del pedido. Un mismo evento puede llegar por varios endpoints.
- Haz el trabajo lento después de aceptar. La firma confirma autenticidad, no orden de llegada. Si un evento 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 o respuesta no 2xx cuenta como fallo. NotPanel reintenta con esperas crecientes y pausa el endpoint API tras 10 fallos consecutivos; 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 un receptor pausado, verifica que el registro esté activo. No supongas que se reenviarán automáticamente todas las entregas históricas fallidas.
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.
- Un evento en dos lotes y un reinicio no deben duplicarlo.
- 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 compara X-Webhook-Delivery-Id con deliveryId del cuerpo verificado y procesa su array events.
¿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.
