Un webhook est une URL de votre système que Grand Shooting appelle quand quelque chose change sur le compte : un média chargé, validé, retaggé, une Référence importée… Votre intégration réagit dans les secondes qui suivent, sans consommer son quota d'API à vérifier s'il y a du nouveau.

Les événements

Un abonnement associe une URL à un topic :

Topic	Déclenché quand
pictures/create	un média est créé (upload, export…)
pictures/update	un média est modifié (statut, tags, nouvelle version, Référence, Code de vue…)
pictures/delete	un média est supprimé
references/create	une Référence est créée
references/update	une Référence est modifiée
references/delete	une Référence est supprimée

Les événements sont génériques : il n'y a pas de topic « média validé ». Pour ne traiter que les médias validés, abonnez-vous à pictures/update et filtrez sur picturestatus dans le message.

S'abonner

Depuis l'administration du compte, menu Équipe > API, rubrique webhooks (administrateurs du compte), ou par l'API :

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

Un abonnement = une URL + un topic : pour suivre plusieurs topics, créez un abonnement par topic (la même URL peut servir pour tous). GET /webhook liste les abonnements du compte, PUT /webhook/{webhook_id} en modifie un, DELETE /webhook/{webhook_id} le supprime.

L'adresse est enregistrée en minuscules. Si votre URL contient un jeton ou un chemin sensible à la casse, choisissez-le en minuscules.

Un nouvel abonnement reçoit ses premiers événements dans la minute.

Le message reçu

Grand Shooting envoie un POST en JSON. Les événements sont regroupés : un message porte jusqu'à 100 objets du même compte et du même topic, et contient directement leur état complet (la même chose que GET /picture/{id} ou 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-ROBE-110", "…": "…" },
    "176": { "picture_id": 176, "bench_root_id": 19, "picturestatus": 40, "ref": "SS26-ROBE-110", "…": "…" }
  }
}

• type vaut picture ou reference ; ids liste les objets concernés.
• data donne l'état de chaque objet au moment de l'envoi (il peut donc être plus récent que l'événement lui-même). Pour un objet supprimé ou illisible, la valeur est null.
• Le champ picture_id (ou reference_id), copie de ids, est déprécié et sera supprimé : utilisez ids.

Livraison et nouvelles tentatives

• Les événements sont envoyés toutes les cinq secondes environ. Plusieurs modifications du même objet dans cet intervalle donnent un seul envoi.
• Répondez par un code 2xx en moins de 5 secondes. Au-delà, l'envoi est considéré comme échoué.
• En cas d'échec, Grand Shooting réessaie après 10 secondes, puis après une minute. Après trois échecs, le message est abandonné et n'est jamais renvoyé.
• Pendant l'attente d'une nouvelle tentative, les envois du compte sont suspendus : un récepteur lent ou en panne retarde tous les webhooks du compte.

Bonnes pratiques

1. Répondez tout de suite, traitez ensuite. Mettez le message dans une file et répondez 200 ; le traitement (téléchargement des fichiers, mise à jour de votre DAM) se fait en arrière-plan.
2. Soyez idempotent. Un même objet peut arriver plusieurs fois (nouvelle tentative, modifications successives), et un update peut arriver sans changement visible. Traitez chaque message comme l'état actuel de l'objet, pas comme une différence.
3. Ne présumez pas de l'ordre entre topics ou entre messages : en cas de doute, relisez l'objet par l'API.
4. Sécurisez l'URL. Les messages ne sont pas signés : utilisez une URL HTTPS longue et imprévisible, vérifiez que account_id est bien un compte attendu, et pour les actions sensibles relisez l'objet par l'API authentifiée à partir de ids plutôt que de vous fier à data.
5. Prévoyez un rattrapage. Un message abandonné n'est pas renvoyé : un traitement périodique qui relit les objets modifiés (GET /picture?date_mod=gte:…) comble les trous éventuels.

Exemple de récepteur (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); // répondre avant de traiter
  queue.push({ account_id, topic, ids });
});