SAUVTEK Pilotage & logiciel

Recevoir un webhook dans Google Apps Script avec doPost

Parsez formulaires classiques et corps JSON, renvoyez une réponse structurée, et appliquez des garde-fous simples sur votre déploiement en application web.

Emmanuel Sauvage 4 min de lecture

Exposer une Google Web App en point d’entrée webhook est une solution éprouvée : pas de serveur à maintenir, accès direct à Sheets, Drive et Gmail. La fonction doPost(e) est le cœur de cette réception. Le piège classique consiste à supposer que tout webhook se présente comme un formulaire HTML : beaucoup de services envoient du JSON brut, et le traitement diffère.

Anatomie de l’objet événement e

Lors d’un POST, Apps Script fournit notamment :

  • e.parameter : map clé/valeur pour les soumissions formulaire (champs en query ou corps x-www-form-urlencoded).
  • e.postData : présent quand un corps est envoyé ; e.postData.type indique le MIME ; e.postData.contents contient le texte brut (souvent JSON).
  • e.queryString : paramètres dans l’URL, utilisables pour un jeton léger (avec prudence : les URLs finissent dans les logs).

Un même endpoint peut donc recevoir un Stripe-like JSON et un ancien formulaire PHP — à condition de brancher explicitement les deux chemins.

Modèle doPost unifié

function doPost(e) {
  const secret = PropertiesService.getScriptProperties().getProperty("WEBHOOK_SECRET");

  try {
    const payload = parsePayload_(e);

    if (secret && payload.secret !== secret) {
      return jsonOutput_({ ok: false, error: "Unauthorized" });
    }

    const result = handleBusinessLogic_(payload);
    return jsonOutput_({ ok: true, result: result });
  } catch (err) {
    console.error(err);
    return jsonOutput_({ ok: false, error: String(err.message || err) });
  }
}

function parsePayload_(e) {
  if (e.postData && e.postData.contents) {
    const mime = (e.postData.type || "").toLowerCase();
    if (mime.indexOf("application/json") !== -1) {
      return JSON.parse(e.postData.contents);
    }
    if (mime.indexOf("application/x-www-form-urlencoded") !== -1) {
      return formUrlEncodedToObject_(e.postData.contents);
    }
    return { raw: e.postData.contents, mime: mime };
  }
  if (e.parameter && Object.keys(e.parameter).length) {
    return Object.assign({}, e.parameter);
  }
  throw new Error("Corps de requête vide");
}

function formUrlEncodedToObject_(body) {
  const out = {};
  body.split("&").forEach(function (pair) {
    const parts = pair.split("=");
    const key = decodeURIComponent(parts[0] || "");
    const val = decodeURIComponent(parts[1] || "");
    if (key) out[key] = val;
  });
  return out;
}

function jsonOutput_(obj) {
  return ContentService.createTextOutput(JSON.stringify(obj)).setMimeType(
    ContentService.MimeType.JSON,
  );
}

function handleBusinessLogic_(payload) {
  // Exemple : journaliser dans une feuille
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Webhooks");
  sheet.appendRow([new Date(), JSON.stringify(payload)]);
  return { received: true };
}

Exécutez le déploiement une fois manuellement si vous ouvrez un classeur hors contexte Web App — getActiveSpreadsheet() ne fonctionne que lorsque le script est lié au fichier actif.

Contenu JSON et en-têtes signés

Certains fournisseurs envoient une signature HMAC dans un en-tête (par exemple X-Signature). UrlFetchApp côté Google ne vous donne pas toujours un accès trivial à tous les en-têtes entrants dans l’objet e historique ; en pratique, les intégrations sensibles passent par un intermédiaire (Cloud Functions, petit serveur, ou constructeur de webhooks) qui vérifie la signature avant de relayer un corps simplifié vers Apps Script.

Si le fournisseur place un secret dans le corps ou la query, vérifiez-le comme dans l’exemple. Stockez ce secret dans Propriétés du script, jamais en clair dans le dépôt.

Réponses attendues par l’appelant

Beaucoup de plateformes relancent en cas d’erreur réseau ou de corps inattendu. Renvoyez toujours un JSON cohérent :

{ "ok": true }

ou

{ "ok": false, "error": "Description lisible" }

Documentez pour vos intégrateurs que Google renvoie souvent HTTP 200 même en cas d’erreur métier : seul le contenu JSON fait foi. Si vous pilotez aussi l’appelant, configurez-le pour lire ok.

Pour les webhooks qui exigent une chaîne exacte (OK, success), ajoutez une branche conditionnelle plutôt que de casser les autres consommateurs.

doGet pour le diagnostic uniquement

function doGet() {
  return ContentService.createTextOutput("Webhook endpoint actif").setMimeType(
    ContentService.MimeType.TEXT,
  );
}

Ouvrez l’URL /exec dans un navigateur pour confirmer le déploiement. Ne traitez pas de données sensibles via GET.

Sécurité sans surcouche inutile

  • HTTPS : implicite sur les URL script.google.com.
  • Secret partagé dans le corps, pas dans l’URL lorsque vous pouvez l’éviter.
  • Validation du schéma : rejeter les champs inconnus ou les types incorrects avant d’écrire en base.
  • Limiter l’effet de bord : une fonction handleBusinessLogic_ courte, sans droits Drive élargis inutiles.
  • Journal des erreurs dans une feuille ou console.error consultable via Exécutions.

Évitez d’exposer un endpoint ouvert sans contrôle « pour aller vite » : le scan automatique des URL Apps Script existe.

Déploiement rappel

  1. Déployer → Nouveau déploiement → Application Web.
  2. Exécuter en tant que moi, accès Toute personne si les appels viennent de l’extérieur.
  3. Utiliser l’URL se terminant par /exec, pas /dev (réservé aux tests avec votre session).

Après modification du code, créez une nouvelle version de déploiement ou mettez à jour le déploiement existant — sinon l’ancien code continue de tourner.

Conclusion

doPost est le bon point d’ancrage pour recevoir des webhooks dans Apps Script, à condition de distinguer e.parameter et e.postData, de renvoyer du JSON explicite et de protéger le déploiement par secret ou relais. Une fois ce socle stable, brancher Sheets, Gmail ou des traitements métier devient une simple extension de handleBusinessLogic_.

Questions fréquentes

doPost ou doGet pour un webhook ?
Les intégrations envoient presque toujours en POST (JSON ou formulaire). Réservez doGet aux tests manuels ou aux vérifications ponctuelles ; n'y placez pas de logique sensible sans authentification.
Pourquoi e.parameter est vide avec du JSON ?
e.parameter est rempli pour les champs application/x-www-form-urlencoded ou multipart. Un corps application/json se lit via e.postData.contents et nécessite JSON.parse.
Comment renvoyer un JSON propre au client ?
Utilisez ContentService.createTextOutput avec le type MimeType.JSON. Documentez que le code HTTP reste 200 côté Google ; le client doit interpréter le champ ok ou error dans le corps.
Dois-je activer « Toute personne » sur le déploiement ?
Seulement si l'appelant n'est pas un utilisateur Google connecté (webhooks SaaS, formulaires publics). Compensez par un secret, une allowlist d'IP si possible, ou un contrôle de charge côté intermédiaire.