Aller au contenu
OpesCare Développeurs
EN FR
Obtenir des clés API

Architecture et flux

Livraison des webhooks

Les webhooks poussent les événements vers votre point d’accès. Chaque livraison est signée pour prouver qu’elle vient d’OpesCare, et les échecs sont réessayés avant d’être marqués en échec.

Le flux

Faites défiler les étapes sous le diagramme, ou survolez-en une, pour la mettre en évidence.

Livraison des webhooks Les événements sont mis en file, signés en HMAC-SHA256, envoyés uniquement à des adresses publiques, réessayés en cas d’échec et rejouables. Événement, livraison en file OpesCare Signer : HMAC- SHA256(t.payload) Worker de file Adresse publique ? Worker de file POST JSON signé Worker de file Adresse refusée hôte privé ou local 2xx : livré Votre point d’accès Vérifier, dédoublonner Votre point d’accès Échec, rejouable rejouer depuis le portail Nouvel essai à 1 min, puis 5 min Worker de file en file publique privée 2xx hors 2xx nouvel essai 3 essais Personne ou appareil Système externe Service OpesCare Contrôle Issue : réussie Issue : refusée Requête Réponse En file / asynchrone Refus ou échec
  1. Événement, livraison en file Chaque abonnement actif à ce type d’événement reçoit une livraison en file.
  2. Signer : HMAC-SHA256(t.payload) L’horodatage et le corps JSON sont signés avec le secret de votre abonnement.
  3. Adresse publique ? Les callbacks vers des adresses privées ou locales sont refusés ; les redirections ne sont pas suivies.
  4. POST JSON signé En-têtes : X-OpesCare-Signature (t=..., v1=...), X-OpesCare-Timestamp, X-OpesCare-Event-Id.
  5. Vérifier, dédoublonner Recalculez le HMAC, rejetez les horodatages anciens et ignorez un Event-Id déjà traité.
  6. 2xx : livré Toute réponse 2xx en moins de 10 secondes marque la livraison comme livrée.
  7. Nouvel essai à 1 min, puis 5 min Une réponse hors 2xx ou un délai dépassé est réessayé, jusqu’à trois tentatives au total.
  8. Échec, rejouable Après la dernière tentative, la livraison est en échec ; rejouez-la depuis le portail développeur.
  9. Adresse refusée Une URL de rappel qui pointe vers une adresse privée, locale ou de lien local n'est jamais appelée.
Comment ce diagramme est vérifié 21 contrôles sur 21 réussis

L'image, les étapes, le PDF et le JSON sont générés à partir d'une seule spécification. Un test automatisé démontre le graphe et vérifie chaque référence ci-dessous dans l'application en fonctionnement.

  • Chaque carte a un identifiant unique
  • Chaque carte a un type connu
  • Chaque flèche relie deux cartes existantes
  • Un seul point de départ (personne, appareil ou partenaire)
  • Chaque carte est atteignable depuis le départ
  • Chaque carte mène à une issue (aucune impasse)
  • Aucun cycle sauf les boucles de nouvel essai déclarées
  • Chaque étape numérotée suit de vraies flèches
  • Les issues terminent le flux
  • Deux cartes ne partagent jamais une case
  • Chaque carte cite sa preuve
  • Chaque route, classe, méthode et réglage existe
  • Chaque icône vient du jeu Lucide
  • Chaque icône correspond au type de sa carte
  • Chaque libellé existe en anglais et en français
  • Chaque libellé tient dans sa carte
  • Aucune flèche ne traverse une carte
  • Deux flèches sans rapport ne se superposent jamais
  • Aucune étiquette de flèche ne couvre une carte ou une autre étiquette
  • Chaque pointe de flèche est visible
  • Deux cartes reliées de types différents ne partagent jamais une couleur
CartePreuve dans le code
Événement, livraison en file method:App\Services\WebhookService::dispatch class:App\Models\WebhookSubscription
Signer : HMAC- SHA256(t.payload) method:App\Jobs\SendWebhookJob::handle class:App\Models\WebhookSecret
Adresse publique ? method:App\Support\PublicUrlGuard::isAllowed method:App\Support\PublicUrlGuard::isPublicIp
POST JSON signé class:App\Models\WebhookDeliveryLog route:docs.webhooks
Adresse refusée method:App\Support\PublicUrlGuard::resolve
2xx : livré class:App\Models\WebhookDeliveryLog
Vérifier, dédoublonner route:docs.webhooks route:portals.developer.webhooks
Échec, rejouable method:App\Jobs\SendWebhookJob::failed route:portals.developer.webhooks.replay method:App\Services\WebhookService::replay
Nouvel essai à 1 min, puis 5 min property:App\Jobs\SendWebhookJob::tries property:App\Jobs\SendWebhookJob::backoff

Tous les flux en JSON

Ce que cela garantit

  • Vous pouvez vérifier que chaque livraison vient d’OpesCare et n’a pas été modifiée.
  • Les webhooks ne sont jamais envoyés vers des adresses privées ou internes.
  • Les échecs sont réessayés et rejouables ; dédoublonnez sur l’identifiant d’événement.

Où cela se trouve dans le code

  • method:App\Services\WebhookService::dispatch
  • class:App\Models\WebhookSubscription
  • method:App\Jobs\SendWebhookJob::handle
  • class:App\Models\WebhookSecret
  • method:App\Support\PublicUrlGuard::isAllowed
  • method:App\Support\PublicUrlGuard::isPublicIp
  • class:App\Models\WebhookDeliveryLog
  • route:docs.webhooks
  • method:App\Support\PublicUrlGuard::resolve
  • route:portals.developer.webhooks
  • method:App\Jobs\SendWebhookJob::failed
  • route:portals.developer.webhooks.replay
  • method:App\Services\WebhookService::replay
  • property:App\Jobs\SendWebhookJob::tries
  • property:App\Jobs\SendWebhookJob::backoff