Un webhook è un URL del vostro sistema che Grand Shooting chiama quando qualcosa cambia nell'account: un media caricato, validato, ritaggato, una Referenza importata… La vostra integrazione reagisce nei secondi successivi, senza consumare la sua quota API per verificare se ci sono novità.

Gli eventi

Un abbonamento associa un URL a un topic:

Topic	Attivato quando
pictures/create	un media viene creato (upload, esportazione…)
pictures/update	un media viene modificato (stato, tag, nuova versione, Referenza, Codice di vista…)
pictures/delete	un media viene eliminato
references/create	una Referenza viene creata
references/update	una Referenza viene modificata
references/delete	una Referenza viene eliminata

Gli eventi sono generici: non esiste un topic "media validato". Per elaborare solo i media validati, abbonatevi a pictures/update e filtrate su picturestatus nel messaggio.

Abbonarsi

Dall'amministrazione dell'account, menu Team > API, sezione WebHooks (amministratori dell'account), oppure tramite l'API:

curl -X POST -H "Authorization: Bearer $GS_TOKEN" -H "Content-Type: application/json" \
  -d '{"address":"https://miaapp.example/gs/webhook-7f3a9c","topic":"pictures/update"}' \
  https://api.grand-shooting.com/v3/webhook

Un abbonamento = un URL + un topic: per seguire più topic, create un abbonamento per topic (lo stesso URL può servire per tutti). GET /webhook elenca gli abbonamenti dell'account, PUT /webhook/{webhook_id} ne modifica uno, DELETE /webhook/{webhook_id} lo elimina.

L'indirizzo viene salvato in minuscolo. Se il vostro URL contiene un token o un percorso sensibile alle maiuscole, sceglietelo in minuscolo.

Un nuovo abbonamento riceve i primi eventi entro un minuto.

Il messaggio ricevuto

Grand Shooting invia un POST in JSON. Gli eventi sono raggruppati: un messaggio contiene fino a 100 oggetti dello stesso account e dello stesso topic, e include direttamente il loro stato completo (lo stesso di GET /picture/{id} o GET /reference/{id}):

{
  "account_id": 10229487,
  "topic": "pictures/update",
  "type": "picture",
  "ids": [175, 176],
  "data": {
    "175": { "picture_id": 175, "bench_root_id": 19, "picturestatus": 50, "ref": "SS26-ABITO-110", "…": "…" },
    "176": { "picture_id": 176, "bench_root_id": 19, "picturestatus": 40, "ref": "SS26-ABITO-110", "…": "…" }
  }
}

• type vale picture o reference; ids elenca gli oggetti interessati.
• data fornisce lo stato di ogni oggetto al momento dell'invio (può quindi essere più recente dell'evento stesso). Per un oggetto eliminato o illeggibile, il valore è null.
• Il campo picture_id (o reference_id), copia di ids, è deprecato e verrà rimosso: usate ids.

Consegna e nuovi tentativi

• Gli eventi vengono inviati circa ogni cinque secondi. Più modifiche dello stesso oggetto in questo intervallo producono un solo invio.
• Rispondete con un codice 2xx entro 5 secondi. Oltre, l'invio è considerato fallito.
• In caso di errore, Grand Shooting riprova dopo 10 secondi, poi dopo un minuto. Dopo tre errori, il messaggio viene abbandonato e non viene mai più inviato.
• Durante l'attesa di un nuovo tentativo, gli invii dell'account sono sospesi: un ricevitore lento o guasto ritarda tutti i webhook dell'account.

Buone pratiche

1. Rispondete subito, elaborate dopo. Mettete il messaggio in una coda e rispondete 200; l'elaborazione (download dei file, aggiornamento del DAM) avviene in background.
2. Siate idempotenti. Uno stesso oggetto può arrivare più volte (nuovi tentativi, modifiche successive), e un update può arrivare senza cambiamenti visibili. Trattate ogni messaggio come lo stato attuale dell'oggetto, non come una differenza.
3. Non presupponete un ordine tra topic o tra messaggi: in caso di dubbio, rileggete l'oggetto tramite l'API.
4. Proteggete l'URL. I messaggi non sono firmati: usate un URL HTTPS lungo e imprevedibile, verificate che account_id sia un account atteso e, per le azioni sensibili, rileggete l'oggetto tramite l'API autenticata a partire da ids invece di fidarvi di data.
5. Prevedete un recupero. Un messaggio abbandonato non viene reinviato: un'elaborazione periodica che rilegge gli oggetti modificati (GET /picture?date_mod=gte:…) colma eventuali lacune.

Esempio di ricevitore (Node.js / Express):

app.post('/gs/webhook-7f3a9c', express.json({ limit: '20mb' }), (req, res) => {
  const { account_id, topic, ids } = req.body;
  if (!EXPECTED_ACCOUNTS.has(account_id)) return res.sendStatus(403);
  res.sendStatus(200); // rispondere prima di elaborare
  queue.push({ account_id, topic, ids });
});