- Documentation
- SDK PHP · Version 0.1
- Webhooks
Webhooks
Sur cette page
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 deX-Social-Timestampet 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.