API Webhooks

Objectif

Recevoir des événements externes sécurisés et idempotents, notamment pour la monétisation.

Périmètre

Webhooks Stripe confirmés, futurs webhooks providers à documenter séparément.

Acteurs/applications consommatrices

• Stripe.
• API Laravel.
• Module Monetization.
• Backoffice pour audit/support.

Authentification requise

• Pas de auth:sanctum.
• Pas de identify.app pour Stripe.
• Validation par signature provider obligatoire.

Permissions/RBAC

Non applicable côté utilisateur. La confiance vient de la signature provider et de l’idempotence.

Endpoints actuels visibles si confirmés

Méthode	Route	Statut
POST	/api/v1/webhooks/stripe	Confirmé.

Endpoints cibles proposés si utile

• Webhooks IA, stockage ou email à définir uniquement si un provider l’exige.
• Ne pas multiplier les webhooks sans besoin opérationnel clair.

Exemple de requête

POST /api/v1/webhooks/stripe
Stripe-Signature: <signature>
Content-Type: application/json

{
  "id": "evt_example",
  "type": "customer.subscription.updated"
}

Exemple de réponse succès

{
  "data": {
    "received": true
  }
}

Exemple d’erreur

{
  "error": "invalid_webhook_signature",
  "message": "Signature webhook invalide."
}

Pagination si applicable

Non applicable.

Rate limiting si applicable

À appliquer prudemment : ne pas bloquer les retries légitimes du provider.

Audit/logs si applicable

Obligatoire :

• identifiant événement provider ;
• type d’événement ;
• statut traitement ;
• idempotence ;
• erreurs.

Ne pas logger de données bancaires sensibles.

Sécurité

• Vérifier la signature avec le secret provider.
• Traiter les événements de manière idempotente.
• Ne pas faire confiance aux payloads sans validation.
• Répondre rapidement et déléguer les traitements lourds à des jobs.

État actuel vs cible

Sujet	État actuel	Cible
Stripe webhook	Route confirmée, sans identify.app ni auth:sanctum.	Traitement idempotent, logs et jobs.
Autres providers	Non confirmés.	Ajout seulement si besoin réel.

Points à confirmer

• Liste des événements Stripe traités.
• Table/log d’idempotence.
• Stratégie de retry.
• Alerting en cas d’échec webhook.