Webhooks 101: cómo te avisa la LotShow API de que una foto está lista

Una foto de estudio tarda un poco en estar lista. Tu sistema podría preguntarle a LotShow cada pocos segundos si ya terminó, o LotShow puede avisar a tu sistema en el momento en que termina. Esa segunda forma es un webhook, y es como la LotShow API entrega los resultados.

Polling o webhooks

Hacer polling significa que tu código llama a GET /v1/jobs/{id} cada cierto tiempo hasta que cambia el estado. Funciona, pero la mayoría de esas llamadas no traen nada nuevo, y cuantos más autos procesas, más llamadas haces.

Un webhook le da la vuelta. Cuando creas un trabajo, le das a LotShow una URL. Cuando el trabajo termina, LotShow envía un POST por HTTPS a esa URL con el resultado. Tu sistema no hace nada hasta que hay algo que hacer.

Los eventos

• job.completed: una foto de estudio está lista, con la URL de la imagen terminada.
• job.failed: una foto no se pudo terminar y su crédito se reembolsó.
• credits.low: tu saldo compartido bajó de 20 créditos.

Tú eliges qué eventos recibe cada endpoint, así un sistema de inventario puede escuchar las fotos terminadas mientras una herramienta de facturación solo se entera de los saldos bajos.

Cómo es una entrega

Un trabajo terminado llega como un pequeño cuerpo JSON:

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

El id es el id de trabajo que recibiste al crearlo. Por eso conviene guardar el id de trabajo junto al número de stock en tu propio sistema: el webhook te dice qué trabajo terminó y tus registros te dicen a qué auto pertenece.

Cómo crear un buen endpoint

1. Responde rápido. Contesta con un estado 2xx en cuanto llegue el evento y haz el trabajo de verdad, como descargar la imagen, en segundo plano.
2. Cuenta con repeticiones. Una entrega puede llegar más de una vez, por ejemplo después de un tiempo de espera agotado, porque LotShow reintenta hasta que tu endpoint responde. Comprueba si ya procesaste un evento antes de volver a actuar.
3. No des por hecho el orden. Dos trabajos enviados con un segundo de diferencia pueden terminar en cualquier orden. Empareja los resultados por id de trabajo, no por el momento en que llegan.
4. Verifica la firma. Cada entrega va firmada con el secreto de firma de tu cuenta, que está en Ajustes, en las cabeceras webhook-id, webhook-timestamp y webhook-signature (el esquema de Standard Webhooks). Rechaza todo lo que no supere la verificación.
5. Regístralo todo. Guarda el cuerpo sin procesar y la hora de cada entrega. Cuando algo no cuadre, el registro será lo primero que mires.

Pruebas antes de salir en vivo

Cada endpoint en Ajustes tiene un botón Enviar prueba, y la API tiene POST /v1/webhooks/{id}/test. Los dos envían un evento de ejemplo a tu endpoint, para que puedas probar tu handler sin gastar créditos. Un inspector de solicitudes o un túnel local son una buena forma de ver exactamente lo que recibe tu endpoint.

¿Listo para empezar? Las claves de API vienen con Pro y Elite: crea una en Ajustes, en Claves de API.