Skip to content
Gillia Developers v1

Guide

Webhooks

Gillia vous appelle quand l’une de vos commandes partenaires change d’état.

Le principe

Quand vous envoyez une commande partenaire (POST /pos/partner-orders), elle sonne sur la caisse du commerçant. L’équipe l’accepte, la prépare et la termine, ou la refuse. Plutôt que de demander l’état en boucle, déclarez une adresse : Gillia vous appelle à chaque changement.

Il faut le droit Commandes partenaires › Envoyer et suivre (pos.orders.write).

Déclarer l’adresse

curl -X PUT https://gillia.app/pos-api/api/v1/sites/{siteId}/pos/partner-webhook \
  -H "Authorization: Bearer gsk_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://commandes.exemple.fr/gillia/webhooks" }'

La réponse contient le secret de signature (whsec_…). Il n’est donné qu’une fois : gardez-le, comme une clé. Pour en obtenir un nouveau, renvoyez la même requête avec "rotateSecret": true (l’ancien cesse aussitôt de valoir).

L’adresse doit être en https et joindre une adresse publique (pas de localhost ni de réseau privé), 500 caractères au plus.

Les événements

ÉvénementQuandPar défaut
order.acceptedL’équipe a accepté la commandeOui
order.rejectedL’équipe a refusé la commande (data.rejectionReason)Oui
order.completedLa commande est terminée ; la caisse a émis le ticket (data.ticketId)Oui
order.readyLa commande est prête (data.readyAt)Sur demande
order.updatedL’heure promise a changé (data.confirmedTime) ou l’équipe a écrit au client (data.sellerNotes)Sur demande

Pour recevoir aussi les deux derniers, listez les événements voulus :

{ "url": "https://commandes.exemple.fr/gillia/webhooks", "events": ["order.accepted", "order.rejected", "order.completed", "order.ready", "order.updated"] }

Exemple de corps reçu :

{
  "id": "evt_3f1c…",
  "type": "order.completed",
  "createdAt": "2026-10-10T17:42:05.120Z",
  "siteId": "6f0c…",
  "data": {
    "externalReference": "APP-2026-000731",
    "orderId": "4821",
    "status": "completed",
    "ticketId": "T0001-000123",
    "updatedAt": "2026-10-10T17:42:04.870Z"
  }
}

Vérifier la signature

Chaque appel porte trois en-têtes :

  • X-Gillia-Event : le type d’événement ;
  • X-Gillia-Delivery : l’identifiant unique de l’événement (le même que id, gardé d’une tentative à l’autre) ;
  • X-Gillia-Signature : t={secondes unix},v1={hex}, où hex est le HMAC-SHA256 en minuscules de "{t}.{corps brut}" avec votre secret.

Vérifiez sur le corps brut, avant toute lecture du JSON, comparez en temps constant, et refusez un t de plus de 5 minutes.

const crypto = require('crypto');

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(',').map(p => p.trim().split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(parts.v1 || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
static bool Verify(string secret, string rawBody, string header)
{
    var parts = header.Split(',').Select(p => p.Trim().Split('=', 2)).ToDictionary(p => p[0], p => p[1]);
    if (!long.TryParse(parts.GetValueOrDefault("t"), out var t) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(parts.GetValueOrDefault("v1") ?? ""));
}

S’envoyer un événement de test

Inutile d’attendre une vraie commande : demandez à Gillia d’envoyer aussitôt un événement webhook.test, signé comme les vrais.

curl -X POST https://gillia.app/pos-api/api/v1/sites/SITE_ID/pos/partner-webhook/test \
  -H "Authorization: Bearer gsk_…"

La réponse dit ce que votre adresse a renvoyé : 200 avec "delivered": true si elle a accusé réception par un 2xx, 502 avec la raison sinon (mauvais code, délai dépassé, injoignable).

Répondre et absorber les répétitions

  • Répondez 2xx en moins de 10 secondes, puis traitez l’événement à part. Tout autre statut, ou pas de réponse à temps, compte comme un échec.
  • En cas d’échec, Gillia réessaie après 30 s, 1 min, 2 min… jusqu’à une heure entre deux tentatives, 12 fois au plus. Les redirections ne sont pas suivies.
  • Un même événement peut donc arriver plusieurs fois : dédoublonnez sur X-Gillia-Delivery.
  • Les événements peuvent arriver dans le désordre : fiez-vous à data.status et data.updatedAt, pas à l’ordre d’arrivée.
  • Dans le doute, lisez l’état à la source : GET /pos/partner-orders/{externalReference}.

Lire ou retirer le webhook

  • GET /pos/partner-webhook : l’adresse et les événements déclarés (jamais le secret).
  • DELETE /pos/partner-webhook : plus aucun appel.