Webhook 101: come la LotShow API ti dice che una foto è pronta

Una foto da studio richiede un po' di tempo. Il tuo sistema potrebbe chiedere a LotShow ogni pochi secondi se ha finito, oppure LotShow può avvisare il tuo sistema nel momento in cui è pronta. Questo secondo modo è un webhook, ed è così che la LotShow API consegna i risultati.

Polling o webhook

Polling significa che il tuo codice chiama GET /v1/jobs/{id} a intervalli regolari finché lo stato non cambia. Funziona, ma la maggior parte di quelle chiamate non porta niente di nuovo, e più auto elabori, più chiamate fai.

Un webhook ribalta la situazione. Quando crei un job, dai a LotShow un URL. Quando il job termina, LotShow invia una POST HTTPS a quell'URL con il risultato. Il tuo sistema non fa nulla finché non c'è qualcosa da fare.

Gli eventi

• job.completed: una foto da studio è pronta, con l'URL dell'immagine finita.
• job.failed: una foto non è stata completata e il suo credito è stato rimborsato.
• credits.low: il tuo saldo condiviso è sceso sotto i 20 crediti.

Scegli tu quali eventi riceve ogni endpoint, così un sistema di gestione dello stock può ascoltare le foto finite mentre uno strumento di fatturazione riceve solo gli avvisi di saldo basso.

Com'è fatta una consegna

Un job completato arriva come un piccolo corpo 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
}

L'id è l'id del job che hai ricevuto quando lo hai creato. Ecco perché conviene salvare l'id del job accanto al numero di stock nel tuo sistema: il webhook ti dice quale job è terminato, e i tuoi dati ti dicono a quale auto appartiene.

Costruire un buon endpoint

1. Rispondi in fretta. Rispondi con uno stato 2xx appena l'evento è arrivato, poi fai il lavoro vero, come scaricare l'immagine, in background.
2. Aspettati ripetizioni. Una consegna può arrivare più di una volta, per esempio dopo un timeout, perché LotShow riprova finché il tuo endpoint non risponde. Verifica se hai già gestito un evento prima di agire di nuovo.
3. Non dare per scontato l'ordine. Due job inviati a un secondo di distanza possono terminare in qualsiasi ordine. Abbina i risultati in base all'id del job, non all'ordine di arrivo.
4. Verifica la firma. Ogni consegna è firmata con il segreto di firma del tuo account, che trovi nelle Impostazioni, negli header webhook-id, webhook-timestamp e webhook-signature (lo schema Standard Webhooks). Rifiuta tutto ciò che non supera la verifica.
5. Registra tutto. Conserva il corpo grezzo e l'orario di ogni consegna. Quando qualcosa non torna, il log è il primo posto in cui guarderai.

Testare prima di andare online

Ogni endpoint nelle Impostazioni ha un pulsante “Invia test”, e l'API ha POST /v1/webhooks/{id}/test. Entrambi inviano un evento di esempio al tuo endpoint, così puoi verificare il tuo gestore senza spendere crediti. Uno strumento di ispezione delle richieste o un tunnel locale vanno benissimo per vedere esattamente cosa riceve il tuo endpoint.

Pronto a iniziare? Le chiavi API sono incluse in Pro ed Elite: creane una nelle Impostazioni, nella scheda Chiavi API.