Aller au contenu
Quiet Social

Webhooks

L'API prévient votre application quand une publication change d'état, par une requête POST signée. Le SDK déclare les endpoints et vérifie les notifications reçues avec Webhook::verify(), en temps constant et dans une fenêtre de tolérance.

Déclarer un endpoint

Un endpoint se déclare dans le panel (page Webhooks) ou avec le SDK, avec le droit webhooks:manage :

$endpoint = $client->webhooks()->create(
    'https://exemple.fr/quiet-social/webhook',
    ['publication.published', 'publication.failed', 'publication_target.failed'],
);

$endpoint->secret; // whsec_… : rendu par cette seule réponse, conservez-le maintenant

$client->webhooks()->test($endpoint->id); // ['delivery_id' => 'whd_…', 'status' => 'pending']

Le secret n'est jamais rendu de nouveau : le perdre impose de supprimer l'endpoint et d'en déclarer un autre. webhooks()->list() rend les endpoints de la clé, webhooks()->update() change l'adresse ou les événements, webhooks()->delete() supprime un endpoint. Le troisième argument de create() limite l'endpoint à une marque.

Le catalogue des événements, les reprises et la suspension d'un endpoint sont décrits dans Webhooks de la référence de l'API.

Vérifier une notification

use QuietSocial\Sdk\Exceptions\InvalidSignature;
use QuietSocial\Sdk\Webhooks\Webhook;

try {
    $event = Webhook::verify(
        (string) file_get_contents('php://input'),
        getallheaders(),
        (string) getenv('QUIET_SOCIAL_WEBHOOK_SECRET'),
    );
} catch (InvalidSignature) {
    http_response_code(400);

    exit;
}

$publication = $event->publication();

if ($publication !== null) {
    // Un événement publication.* : agir selon le statut que porte le corps.
    if ($publication->status === 'published') {
        // …
    }
} elseif (isset($event->data['target'])) {
    // Un événement publication_target.* : un réseau, et l'identifiant de sa publication.
    $statut = $event->data['target']['status'];
    $publicationId = $event->data['publication_id'];
}

http_response_code(204);
  • verify() vérifie la signature HMAC-SHA256 de X-Social-Timestamp et du corps brut, en temps constant, et refuse un horodatage à plus de 300 secondes de l'instant présent. Le quatrième argument change la fenêtre ; le cinquième fixe l'instant présent, pour les tests.
  • Passez le corps tel que reçu : décodé puis réencodé, il ne correspondrait plus.
  • Le secret est obligatoire. Un secret vide ou blanc lève InvalidArgumentException : une variable d'environnement manquante échoue bruyamment au lieu d'accepter des notifications forgées.
  • Les noms d'en-têtes peuvent être en toute casse, et les valeurs des chaînes ou des listes, tels que getallheaders() et $request->headers->all() les donnent.
  • Une requête douteuse (en-tête manquant, horodatage hors fenêtre, signature fausse, corps qui n'est pas un objet JSON) lève InvalidSignature : répondez par un statut d'erreur et n'agissez jamais sur son corps.

Ce qui est signé, et ce qui ne l'est pas

Seuls l'horodatage et le corps sont signés. $event->name (X-Social-Event) et $event->deliveryId (X-Social-Delivery) viennent d'en-têtes que pourrait changer quiconque est en mesure de rejouer une requête. Déduisez l'événement du corps :

Corps Événement Lecture
{"publication": …} publication.* $event->publication() rend la publication, avec ses cibles.
{"target": …, "publication_id": …} publication_target.* $event->data['target'] et $event->data['publication_id'].
{"destination": …} destination.disabled $event->data['destination'].
{"social_connection": …, "destinations": …} social_connection.requires_reconnect $event->data['social_connection'].
{"message": …, "sent_at": …} webhook.test Rien à faire, sinon répondre 2xx.

Décidez sur le corps (la publication et son statut) et prenez le nom pour une indication. $event->deliveryId est stable d'une tentative à l'autre, ce qui aide à écarter une livraison déjà traitée, mais gardez le traitement lui-même idempotent : appliquer deux fois le statut que porte le corps ne doit rien changer. $event->signedAt est l'instant de signature de cette tentative, pas celui de l'événement : une livraison retentée est signée de nouveau.

En Laravel

use Illuminate\Http\Request;
use QuietSocial\Sdk\Exceptions\InvalidSignature;
use QuietSocial\Sdk\Webhooks\Webhook;

Route::post('/quiet-social/webhook', function (Request $request) use ($webhookSecret) {
    try {
        $event = Webhook::verify(
            $request->getContent(),
            $request->headers->all(),
            $webhookSecret,
        );
    } catch (InvalidSignature) {
        abort(400);
    }

    // …

    return response()->noContent();
});

$webhookSecret est le secret whsec_…, lu dans votre propre réglage (une variable d'environnement derrière une valeur de configuration, par exemple). Excluez cette route de la protection CSRF de votre application, et répondez vite : traitez la notification dans un job si elle demande du travail.