- Documentation
- API · Version 1.0
- Webhooks
Webhooks
Sur cette page
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, avecRetry-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
301ou un302compte 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-Deliveryest 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.