Aller au contenu
Quiet Social

Webhooks

Avec un secret de signature, le paquet enregistre une route qui reçoit les notifications de Quiet Social, vérifie chacune, tient à jour le statut de vos posts et lève les événements Laravel correspondants.

La route

Renseignez QUIET_SOCIAL_WEBHOOK_SECRET et le paquet enregistre POST /social/webhook (la clé webhook_path), nommée social.webhook. Sans secret, la route n'existe pas : une route qui accepterait des corps non signés laisserait n'importe qui inventer l'état de vos publications. Elle est hors du groupe de middlewares web : ni session, ni jeton CSRF.

Déclarez son adresse dans le panel de Quiet Social, page Webhooks : une adresse en https joignable depuis Internet, avec les événements voulus. Le secret (whsec_…) n'est affiché qu'une fois, à la déclaration du webhook. Le parcours est décrit dans le guide, et le contenu de chaque notification dans la référence des webhooks.

La signature

Chaque requête est vérifiée par le SDK sur le corps brut, dans la tolérance de webhook_tolerance secondes (300 par défaut). Une signature absente, fausse ou expirée répond 401, et rien n'est cru. Trop large, la tolérance laisse rejouer un appel intercepté ; trop étroite, elle casse dès qu'une horloge dérive.

Les doublons

  • Reprises. Une reprise de l'API, signée de nouveau avec un nouvel horodatage, est reconnue à son X-Social-Delivery, son événement et son corps pendant webhook_replay_window secondes. Les 12 heures par défaut couvrent tout le calendrier de reprises de l'API (6 tentatives, sur environ 8 h 36).
  • Rejeu. La même requête signée, rejouée sous un autre identifiant de livraison, est reconnue à sa signature pendant deux fois la tolérance.
  • Échec du traitement. Une livraison dont le traitement lève une exception est oubliée, pour que la reprise suivante passe.

Ces livraisons vivent dans votre cache par défaut, qui doit être partagé par tous les serveurs web : sans cela, un serveur ne reconnaît pas ce qu'un autre a déjà traité.

L'ordre et les statuts

  • Le lien de la publication est mis à jour avant que l'événement soit levé.
  • Un statut non final ne remplace jamais un statut final, sauf une publication échouée relancée depuis le panel, qui rouvre son lien.
  • Une notification arrivée avant le lien d'un post tout juste créé est gardée quelques minutes, et appliquée dès que le lien est écrit.
  • Une publication annulée ou échouée dans Quiet Social ferme le lien automatique qui la suivait.

Les réponses

Chaque notification signée est acquittée par 204, y compris :

  • les événements que le paquet ne relaie pas (publication.scheduled, publication.processing…), qui mettent tout de même à jour le lien de leur publication ;
  • un événement que contredit le statut de son corps signé (publication.failed sur une publication publiée), qui est journalisé et ne lève rien.

Une erreur ferait retenter l'API, puis suspendre l'endpoint après des échecs répétés.