Aller au contenu
Quiet Social

Webhooks

Un webhook prévient votre application quand une publication change d'état, sans qu'elle ait à interroger l'API. Quiet Social envoie une requête POST signée à l'adresse que vous déclarez.

Les endpoints se déclarent par l'API, avec le périmètre webhooks:manage, ou depuis le tableau de bord, menu Webhooks (voir le guide). Les deux voies mènent au même endpoint, avec les mêmes règles.

Déclarer un endpoint : POST /webhooks

Champ Type Requis Note
url texte (2048) oui En https, joignable depuis internet.
events liste oui Au moins un événement du catalogue.
brand_id brd_… non Limite l'endpoint aux événements d'une marque. Absent, il couvre tout l'espace de travail.
curl -X POST https://quietsocial.dev/api/v1/webhooks \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
        "url": "https://example.com/quiet-social/webhook",
        "events": ["publication.published", "publication_target.failed"]
      }'

201 Created :

{
  "data": {
    "id": "whe_01k4b90a7x1y2z3b4c5d6e7f8g",
    "url": "https://example.com/quiet-social/webhook",
    "events": ["publication.published", "publication_target.failed"],
    "status": "active",
    "failure_count": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "secret": "whsec_…",
    "created_at": "2026-10-01T09:20:15+00:00"
  },
  "reveal_secret": true
}

Conservez secret maintenant. Il n'est rendu qu'à la création : aucune lecture ultérieure ne le montre. Le perdre impose de supprimer l'endpoint et d'en déclarer un nouveau.

L'adresse est vérifiée dès la déclaration. Sont refusés, en 422 sur le champ url avec la raison exacte :

  • tout autre schéma que https ;
  • les noms réservés à la machine ou au réseau local (localhost, .local, .internal, un nom sans point…) ;
  • les adresses privées ou réservées, et tout nom dont la résolution DNS mène à une telle adresse.

Un client rattaché à une marque déclare toujours des endpoints de sa marque. Un client d'espace qui envoie brand_id doit désigner une marque de son espace ; sinon, la déclaration est refusée en 422 sur le champ brand_id. GET /brands donne les identifiants valides.

Codes : 201, 401, 403, 422, 429.

Lister : GET /webhooks

Les endpoints visibles par le client, dans l'ordre de leur création, sans pagination. Un client rattaché à une marque voit les endpoints de cette marque et ceux qui couvrent tout l'espace. Il lit ces derniers, mais ne les modifie, ne les supprime ni ne les teste : ces trois routes lui répondent 403 avec endpoint_shared.

secret n'apparaît pas. L'état de santé, si : status vaut active ou suspended, failure_count compte les livraisons échouées consécutives, last_success_at et last_failure_at datent les dernières issues.

Codes : 200, 401, 403, 429.

Modifier : PATCH /webhooks/{id}

Change l'adresse, la liste d'événements, ou les deux. Un champ absent reste tel quel. L'adresse est vérifiée comme à la déclaration.

curl -X PATCH https://quietsocial.dev/api/v1/webhooks/whe_01k4b90a7x1y2z3b4c5d6e7f8g \
  -u "$QUIET_CLIENT_ID:$QUIET_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"events": ["publication.failed", "publication_target.failed"]}'

200 OK, avec l'endpoint relu, sans secret. La marque d'un endpoint et son status ne se modifient pas.

Codes : 200, 401, 403, 404, 422, 429.

Supprimer : DELETE /webhooks/{id}

204 No Content. La suppression est définitive.

Codes : 204, 401, 403, 404, 429.

Tester : POST /webhooks/{id}/test

Envoie une notification de contrôle, par exactement le même chemin qu'une vraie : même signature, mêmes en-têtes, mêmes reprises.

{
  "data": {
    "delivery_id": "whd_01k4b91b8y2z3a4c5d6e7f8g9h",
    "status": "pending"
  }
}

202 Accepted : la livraison est mise en file, elle n'a pas encore eu lieu. Son issue se constate sur votre endpoint, ou dans last_success_at et last_failure_at.

L'événement est webhook.test, hors du catalogue : votre endpoint le reçoit même s'il ne s'y est pas abonné. Ne le faites pas tomber dans une branche d'erreur « événement inconnu ». Son corps :

{
  "message": "This is a check notification sent from Quiet Social.",
  "sent_at": "2026-10-01T09:21:03+00:00"
}

Deux refus :

  • un endpoint suspendu ne reçoit rien : 409 endpoint_suspended, « This endpoint is suspended and receives nothing: reactivate it first. » ;
  • chaque test part réellement vers votre adresse : 5 par minute et par endpoint au plus, tableau de bord et API confondus. Au-delà, 429 too_many_requests, avec Retry-After.

Codes : 202, 401, 403, 404, 409, 429.

Catalogue des événements

Événement Émis quand
publication.created Une publication est créée, depuis l'API ou le tableau de bord.
publication.approved Une publication soumise à validation est validée, par l'équipe ou par le client.
publication.scheduled Une publication passe en scheduled : libérée par publish, ou relancée par retry après s'être terminée.
publication.processing Au moins une cible est partie et une autre n'a pas encore abouti.
publication.published Toutes les cibles sont publiées.
publication.partially_published Toutes les cibles ont une issue, et une partie seulement est publiée.
publication.failed Toutes les cibles ont une issue, et aucune n'est publiée.
publication.cancelled Toutes les cibles sont annulées.
publication_target.published Une cible est publiée.
publication_target.failed Une cible échoue, ou passe en requires_reconnect : de votre point de vue, la livraison n'aura pas lieu sans intervention.
social_connection.requires_reconnect Une connexion cesse de pouvoir publier : son accès a expiré, a été révoqué, ou le réseau l'a refusé. Émis une fois, au passage ; pas à chaque vérification tant qu'elle reste à rétablir.
destination.disabled Une destination active cesse de l'être : désactivée par un membre de l'équipe, ou devenue inaccessible.

Un endpoint limité à une marque ne reçoit que les événements de cette marque. Une connexion appartient à l'espace de travail et non à une marque : l'endpoint d'une marque n'apprend social_connection.requires_reconnect que si la connexion porte des destinations de cette marque, et reçoit alors un corps réduit (voir plus bas).

Ce que reçoit votre endpoint

POST /quiet-social/webhook HTTP/1.1
Content-Type: application/json
X-Social-Event: publication.published
X-Social-Delivery: whd_01k4b91b8y2z3a4c5d6e7f8g9h
X-Social-Timestamp: 1790846463
X-Social-Signature: 6812dcecedae62e31509cc73c4f8c61291eae937dac924bf42273aba9c36a7dc
En-tête Contenu
X-Social-Event Le nom de l'événement. Il n'est pas répété dans le corps.
X-Social-Delivery L'identifiant whd_… de la livraison, le même à chaque tentative.
X-Social-Timestamp L'horodatage Unix de la signature, refait à chaque tentative.
X-Social-Signature HMAC-SHA256(timestamp + "." + corps brut, secret), en hexadécimal.

Pour un événement publication.*, le corps porte la publication, exactement comme GET /publications/{id} la rend :

{
  "publication": {
    "id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
    "status": "published",
    "external_reference": "article-42",
    "targets": ["…"]
  }
}

Pour un événement publication_target.*, il porte la cible, exactement comme dans targets[], et l'identifiant de sa publication :

{
  "target": {
    "destination_id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
    "network": "facebook",
    "provider": "meta",
    "status": "published",
    "external_url": "https://www.facebook.com/…",
    "attempts": 1,
    "error": null
  },
  "publication_id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8"
}

Ces deux exemples sont abrégés : les champs sont tous ceux décrits dans Publications.

Pour destination.disabled, le corps porte la destination, exactement comme GET /destinations/{id} la rend :

{
  "destination": {
    "id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
    "network": "facebook",
    "name": "Fabrique du Nord",
    "status": "disabled",
    "can_publish": false,
    "capabilities": {"…": "…"}
  }
}

Pour social_connection.requires_reconnect, il porte la connexion et ses destinations :

{
  "social_connection": {
    "provider": "meta",
    "status": "requires_reconnect",
    "error_code": "meta.token_invalid",
    "account": "Camille Martin",
    "error_message": "L'autorisation Meta de ce compte n'est plus valide ; reconnectez-le."
  },
  "destinations": [
    { "id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4", "network": "facebook", "name": "Fabrique du Nord" }
  ]
}

status vaut expired, revoked ou requires_reconnect. Un endpoint limité à une marque reçoit un corps réduit : ni account ni error_message, et seulement les destinations de sa marque. La connexion n'a pas d'identifiant public ; rétablissez-la depuis le tableau de bord.

Vérifier la signature

Vérifiez la signature sur le corps brut, avant tout décodage JSON : un corps décodé puis réencodé n'a plus les mêmes octets. Refusez un horodatage trop ancien — cinq minutes est une bonne fenêtre — pour qu'une requête interceptée ne puisse pas être rejouée.

use Illuminate\Http\Request;

Route::post('/quiet-social/webhook', function (Request $request) {
    $timestamp = (string) $request->header('X-Social-Timestamp');
    $signature = (string) $request->header('X-Social-Signature');

    $expected = hash_hmac('sha256', $timestamp.'.'.$request->getContent(), config('services.quiet_social.webhook_secret'));

    abort_unless(hash_equals($expected, $signature), 401);
    abort_if(abs(time() - (int) $timestamp) > 300, 401);

    // Une même livraison peut arriver deux fois : ignorez un X-Social-Delivery déjà traité.
    // …

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

Excluez cette route de la protection CSRF de votre application.

Livraison et reprises

  • Une livraison réussit quand votre endpoint répond un statut 2xx. Répondez vite et traitez ensuite : la requête est abandonnée au bout de 10 secondes, et la connexion au bout de 5.
  • Les redirections ne sont pas suivies. Un 301 ou un 302 compte comme un échec : déclarez l'adresse finale.
  • Une livraison échouée est retentée, jusqu'à six tentatives en tout, après 1 minute, 5 minutes, 30 minutes, 2 heures puis 6 heures.
  • Une même livraison peut arriver plus d'une fois. X-Social-Delivery est stable d'une tentative à l'autre : servez-vous-en pour ignorer un doublon.

Suspension

Après 10 livraisons consécutives échouées (chacune après toutes ses tentatives), l'endpoint passe en suspended et ne reçoit plus rien. Une livraison réussie remet le compteur à zéro.

Un endpoint dont l'adresse se révèle interdite au moment de l'envoi — un nom qui pointe désormais vers une adresse privée, par exemple — est suspendu immédiatement.

Un endpoint suspendu ne se réactive pas par l'API. Corrigez la cause, puis Réactiver depuis le tableau de bord, menu Webhooks : l'adresse est vérifiée de nouveau, le compteur d'échecs repart de zéro et le secret ne change pas. Une adresse qui mène toujours vers une destination interdite empêche la réactivation.