Webhooks sortants

Quand Zapier ne suffit pas — vous voulez écrire votre propre backend, exécuter vos propres automatisations, acheminer les événements vers un data warehouse, ou déclencher des services que Zapier ne prend pas en charge — les webhooks sortants vous donnent le flux brut.

Un webhook est juste un endpoint HTTPS que vous hébergez. GCM y POST du JSON dès qu'il se passe quelque chose dans votre organisation. Même infrastructure de livraison que l'intégration Zapier, mais pointée vers votre URL au lieu de celle de Zapier.

Quand utiliser des webhooks plutôt que Zapier

• Utilisez Zapier quand la destination est l'une des 6 000+ applications déjà prises en charge par Zapier, vous ne voulez pas héberger de code, et la tarification par tâche de Zapier vous convient.
• Utilisez les webhooks quand vous avez votre propre backend, vous voulez un seul payload poussé vers votre warehouse / queue / Lambda, ou vous voulez un coût nul par événement au-delà de votre propre hébergement.

Les deux partagent la même politique de réessai, le même schéma de signature et le même journal de livraison. La seule différence est l'URL qui reçoit le POST.

S'abonner à des événements

Il existe deux façons de créer un abonnement à un webhook :

Via l'API

POST vers /v1/subscriptions avec votre clé API :

curl -X POST https://api.geniuschurchmanager.com/v1/subscriptions \
  -H "Authorization: Bearer gcm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "member.created",
    "target_url": "https://your-server.example.com/gcm/webhook"
  }'

La réponse contient un subscription_id. Conservez-le — vous en aurez besoin pour désactiver plus tard.

Via l'interface

Dans Integrations → Zapier, l'onglet Subscriptions affiche chaque abonnement actif, qu'il ait été créé par Zapier ou par un script maison. Vous pouvez désactiver mais pas créer d'abonnements depuis l'interface — c'est intentionnel, puisque les URL cibles doivent être gérées par du code.

Événements disponibles

Même catalogue que Zapier :

Événement	Déclencheur
member.created	Toute nouvelle ligne de membre
member.updated	Modifications de champs suivis sur un membre
donation.created	Ligne de don insérée
donation.refunded	Remboursement traité
attendance.recorded	Pointage ou assiduité enregistrés
workflow.completed	Exécution de workflow terminée
form.submitted	Formulaire public soumis
group.member_added	Membre ajouté à un groupe / ministère

Consultez la référence API des webhooks pour la forme exacte des champs de chaque événement.

Vérification de signature

Chaque POST porte un en-tête X-GCM-Signature — un condensé HMAC-SHA256 hex sur le corps brut de la requête, signé avec le secret de votre abonnement.

import crypto from "node:crypto";

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

WARNING

Vérifiez toujours la signature avant d'analyser le corps ou de faire quoi que ce soit avec le payload. Des POST non signés ou invalides vers votre endpoint pourraient venir de n'importe qui.

Le secret de signature est affiché une seule fois lorsque l'abonnement est créé. Stockez-le dans votre gestionnaire de secrets.

Contrat de réponse

Votre endpoint doit :

• Renvoyer HTTP 2xx en moins de 10 secondes — nous traitons tout le reste comme un échec.
• Être idempotent — nous pouvons réessayer, et le même ID d'événement peut arriver deux fois. Le payload inclut un delivery_id que vous pouvez utiliser pour dédupliquer.
• Effectuer le travail en asynchrone s'il est lent. Persistez le payload dans une file et renvoyez 200 immédiatement ; traitez à votre rythme.

Une réponse 4xx est traitée comme « cette requête était malformée et ne réussira pas au réessai. » Nous ne réessayons pas. Une 5xx est traitée comme « l'endpoint a une mauvaise journée » et nous réessayons avec un délai exponentiel.

Politique de réessai

Les livraisons échouées sont réessayées avec un délai exponentiel :

Tentative	Délai après l'échec précédent
1	initial
2	1 minute
3	5 minutes
4	25 minutes
5	2 heures

Après 5 échecs au total, la ligne de livraison est marquée failed et nous arrêtons. Après 10 échecs consécutifs sur l'ensemble des livraisons, l'abonnement lui-même est désactivé automatiquement — vous verrez un badge rouge dans l'interface et nous enverrons un e-mail à l'admin de l'organisation.

Inspecter les livraisons

L'onglet Recent deliveries dans Integrations → Zapier affiche les 50 dernières tentatives sur l'ensemble des abonnements (Zapier et webhooks confondus).

Chaque ligne contient le statut HTTP, le nombre de réessais, un extrait de la réponse et l'horodatage. Pour résoudre « pourquoi l'événement X ne s'est-il pas déclenché », c'est le premier endroit où regarder.

Webhooks entrants (la direction inverse)

Vous pouvez aussi faire que votre système POST dans GCM pour déclencher des workflows. Configurez un déclencheur webhook entrant dans n'importe quel workflow :

1. Construisez un workflow avec un nœud déclencheur Webhook.
2. GCM vous donne une URL avec un slug unique (/functions/v1/receive-webhook/{slug}).
3. Configurez votre système externe pour POST vers cette URL avec X-Webhook-Signature (HMAC-SHA256 sur le corps en utilisant le secret que GCM vous montre).
4. Chaque POST valide démarre une nouvelle exécution de workflow avec le payload disponible pour les étapes suivantes.

C'est le chemin pour recevoir des événements de systèmes qui n'ont pas d'intégration Zapier — votre logiciel de comptabilité, votre plateforme de diffusion en direct, un site d'inscription personnalisé.

Limites de débit

Limite	Par défaut
Abonnements actifs par organisation	100
Débit de livraison par abonnement	60 / minute
Taille du payload	256 Ko
Débit des webhooks entrants	60 / minute / slug

Références croisées

• Référence API des webhooks — formes exactes des payloads d'événements.
• Clés d'API — créer des clés pour gérer les abonnements.
• Zapier — même moteur, destination sans code.
• Workflows — détails des déclencheurs webhook entrants.