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énement | Quand | Par défaut |
|---|---|---|
order.accepted | L’équipe a accepté la commande | Oui |
order.rejected | L’équipe a refusé la commande (data.rejectionReason) | Oui |
order.completed | La commande est terminée ; la caisse a émis le ticket (data.ticketId) | Oui |
order.ready | La commande est prête (data.readyAt) | Sur demande |
order.updated | L’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 queid, 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.statusetdata.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.