Webhooks (GitHub, Stripe, entrants)

Puwapi reçoit des webhooks (entrants) et émet des notifications internes vers Convex. Voici les webhooks entrants exposés et comment ils se sécurisent.

Principe commun¶

• Les endpoints de webhook sont [AllowAnonymous] (pas de JWT) mais vérifient une signature ou un secret.
• Le corps brut est lu tel quel pour valider la signature — aucun parsing préalable qui consommerait le flux.
• Une source inconnue ou une signature absente renvoie souvent un 200 silencieux (pour ne rien révéler) ; une signature invalide renvoie 403.

GitHub → Work¶

POST /api/work/github/webhook

• Signature : X-Hub-Signature-256 = sha256=<hex>, HMAC SHA-256 du corps brut avec le webhookSecret configuré par organisation.
• Événements traités : issues et pull_request, actions closed / reopened.
• Effet : mappe le statut de l'item lié (closed → done/resolved, reopened → in_progress), idempotent.
• Voir Synchroniser Work avec GitHub.

Stripe → Billing¶

POST /api/webhooks/stripe

• Signature Stripe vérifiée sur le corps brut.
• Effet : met à jour l'abonnement et invalide le cache de droits (propagation ≤ 15 s).

Entrants Chat¶

POST /api/integrations/{token} (et POST /api/integrations/messages)

• Authentifié par un jeton d'intégration dans l'URL.
• Effet : poste un message dans un canal (alertes, robots, outils tiers).

Sortants : notifications internes (Convex)¶

Les modules émettent vers Convex sur /<module>/notify, protégé par <MODULE>_WEBHOOK_SECRET. Ce ne sont pas des webhooks publics : c'est le canal temps réel interne (voir Temps réel (Convex)).

Bonnes pratiques côté intégrateur¶

• Stockez le secret de manière sûre ; utilisez-en un fort et unique par intégration.
• Répondez rapidement (2xx) et traitez de façon idempotente : un webhook peut être rejoué.
• Ne vous fiez pas à l'ordre d'arrivée ; réconciliez avec l'API si nécessaire.