Avisos automáticos cuando termina un trabajo

Consultar en bucle funciona y es la forma correcta de empezar. Cuando tienes más de un puñado de trabajos en marcha, que te avisen es mejor que preguntar una y otra vez.

Eso es todo lo que es un aviso aquí. Das una dirección y un trabajo terminado se envía a ella.

Qué configuras y dónde

Las direcciones se registran en la sección de avisos de tu cuenta, no a través de la propia API. No hay llamada que cree una.

Eso es un límite deliberado y no una función que falte. Una dirección que recibe tus resultados no es algo que una clave filtrada deba poder cambiar.

Aportas una URL que controlas y recibes a cambio un secreto de firma. Guárdalo igual que guardas la clave.

Solo se envían dos cosas, una para un trabajo que terminó bien y otra para uno que falló.

No llega nada mientras un trabajo está en cola o procesando. Si quieres progreso, el bucle de consulta sigue siendo la vía.

Dos eventos es una superficie pequeña y esa es la gracia. No hay nada que filtrar ni modelo de suscripción que configurar.

Qué llega a tu dirección

Un envío con un cuerpo que describe el evento y unas cabeceras que te permiten comprobarlo.

• Una cabecera de evento que dice si el trabajo terminó bien o falló.
• Un identificador de entrega único de ese intento.
• Una marca de tiempo en segundos.
• Una firma, con prefijo para indicar qué esquema la produjo.

El cuerpo contiene el trabajo con la misma forma que habrías obtenido consultándolo. Nada nuevo que aprender y ningún segundo analizador que escribir.

Esa simetría merece la pena aprovecharla. Escribe una función que gestione un trabajo terminado y llámala desde tu bucle y desde tu dirección.

También hace indoloro moverse entre las dos. Empezar consultando y añadir una dirección después casi no cuesta nada si el manejador ya estaba separado.

Verificar que de verdad viene de nosotros

Esta es la parte que hay que acertar antes de hacer nada con el contenido, porque a una URL pública puede enviar cualquiera.

Calcula un hash sobre la marca de tiempo y el cuerpo en crudo usando tu secreto de firma, y compáralo con la cabecera de firma.

Dos detalles deciden si esto funciona. Compara con una función de tiempo constante en lugar de una igualdad de cadenas normal, y calcula el hash sobre el cuerpo exactamente como llegó.

Si analizas el cuerpo a objeto y lo vuelves a serializar antes del hash, los bytes cambian y nunca coincidirá. Ese error le cuesta a la gente una tarde.

Rechaza además cualquier cosa con una marca de tiempo de más de cinco minutos. La firma en sí no caduca, así que esa comprobación de edad es lo que impide que alguien repita una entrega capturada antes.

Cuando monté esto la primera vez me salté la comprobación de edad y solo la añadí tras leer por qué existe. Son dos líneas y cierran un agujero real.

Las comprobaciones del primer día

Unos pocos hábitos hacen una dirección que aguanta en condiciones reales y no solo en pruebas.

• Responde rápido y haz el trabajo después. Una dirección lenta parece una rota.
• Espera la misma entrega más de una vez y haz que procesarla dos veces sea inofensivo.
• Gestiona el evento de fallo, no solo el de éxito. Los créditos ya están devueltos, así que tu tarea es decidir si reintentas.
• Registra el identificador de entrega para poder rastrear un evento concreto después.

Las entregas duplicadas son normales en cualquier sistema de avisos. Anclar tu manejador al identificador del trabajo en lugar de asumir un mensaje por trabajo elimina toda esa clase de problema.

El orden tampoco está garantizado. Dos trabajos que terminan cerca pueden llegar en cualquier secuencia, así que nunca deduzcas nada de cuál llegó antes.

Una respuesta 2xx significa entregado. Cualquier otra se reintenta dos veces más, alrededor de dos y ocho segundos después, y un reintento reutiliza el mismo identificador de entrega.

Responder 404 o 410 detiene los reintentos del todo, que es la forma educada de retirar una dirección en la que ya no quieres entregas.

Mantén el bucle de consulta como respaldo durante un tiempo. Una dirección que deja de recibir en silencio es más difícil de notar que un bucle que deja de terminar.

Un túnel local es la forma más fácil de desarrollar contra esto. Apuntar la dirección a tu equipo te deja leer entregas reales en lugar de inventarte una.

Registra el cuerpo en crudo antes de analizarlo, al menos mientras construyes. Casi todos los problemas de firma se ven en cuanto puedes mirar exactamente qué llegó.

Cuando funcione, sigue registrando el identificador de entrega y quita el resto. Los cuerpos contienen tus resultados y no deben quedarse en un registro para siempre.

La lista completa de cabeceras y la construcción exacta de la firma están en la documentación de la API pública, que conviene leer una vez en lugar de adivinar.

Y los avisos solo compensan en trabajo que se repite. Para un lote único como una ficha de Etsy que limpié antes de publicarla, un bucle de consulta es menos trabajo y termina el mismo día.

Verifica, responde rápido, espera duplicados y gestiona el fallo. Cuatro reglas y la dirección se mantiene aburrida.