- Documentación
- SDK PHP · Versión 0.1
- Webhooks
Webhooks
En esta página
La API avisa a tu aplicación cuando una publicación cambia de estado, con una petición POST firmada. El SDK declara los endpoints y verifica las notificaciones recibidas con Webhook::verify(), en tiempo constante y dentro de una ventana de tolerancia.
Declarar un endpoint
Un endpoint se declara en el panel (página Webhooks) o con el SDK, con el permiso webhooks:manage:
$endpoint = $client->webhooks()->create(
'https://ejemplo.es/quiet-social/webhook',
['publication.published', 'publication.failed', 'publication_target.failed'],
);
$endpoint->secret; // whsec_…: solo lo devuelve esta respuesta, guárdalo ahora
$client->webhooks()->test($endpoint->id); // ['delivery_id' => 'whd_…', 'status' => 'pending']
El secreto no se vuelve a devolver nunca: perderlo obliga a eliminar el endpoint y declarar otro. webhooks()->list() devuelve los endpoints de la clave, webhooks()->update() cambia la dirección o los eventos, webhooks()->delete() elimina un endpoint. El tercer argumento de create() limita el endpoint a una marca.
El catálogo de eventos, los reintentos y la suspensión de un endpoint se describen en Webhooks de la referencia de la API.
Verificar una notificación
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 evento publication.*: actuar según el estado que lleva el cuerpo.
if ($publication->status === 'published') {
// …
}
} elseif (isset($event->data['target'])) {
// Un evento publication_target.*: una red, y el identificador de su publicación.
$estado = $event->data['target']['status'];
$publicationId = $event->data['publication_id'];
}
http_response_code(204);
verify()comprueba la firma HMAC-SHA256 deX-Social-Timestampy del cuerpo en bruto, en tiempo constante, y rechaza una marca de tiempo a más de 300 segundos del momento actual. El cuarto argumento cambia la ventana; el quinto fija el momento actual, para las pruebas.- Pasa el cuerpo tal como llegó: decodificado y vuelto a codificar, ya no coincidiría.
- El secreto es obligatorio. Un secreto vacío o en blanco lanza
InvalidArgumentException: una variable de entorno que falta falla de forma visible en lugar de aceptar notificaciones falsificadas. - Los nombres de cabecera pueden ir en cualquier combinación de mayúsculas y minúsculas, y los valores ser cadenas o listas, tal como los dan
getallheaders()y$request->headers->all(). - Una petición dudosa (cabecera ausente, marca de tiempo fuera de la ventana, firma incorrecta, cuerpo que no es un objeto JSON) lanza
InvalidSignature: responde con un estado de error y no actúes nunca sobre su cuerpo.
Lo que está firmado, y lo que no
Solo la marca de tiempo y el cuerpo están firmados. $event->name (X-Social-Event) y $event->deliveryId (X-Social-Delivery) vienen de cabeceras que podría cambiar quien esté en condiciones de reenviar una petición. Deduce el evento del cuerpo:
| Cuerpo | Evento | Lectura |
|---|---|---|
{"publication": …} |
publication.* |
$event->publication() devuelve la publicación, con sus destinos. |
{"target": …, "publication_id": …} |
publication_target.* |
$event->data['target'] y $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 |
Nada que hacer, salvo responder 2xx. |
Decide según el cuerpo (la publicación y su estado) y toma el nombre como una indicación. $event->deliveryId es estable de un intento a otro, lo que ayuda a descartar una entrega ya procesada, pero mantén el propio procesamiento idempotente: aplicar dos veces el estado que lleva el cuerpo no debe cambiar nada. $event->signedAt es el momento en que se firmó este intento, no el del evento: una entrega reintentada se vuelve a firmar.
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 es el secreto whsec_…, leído en tu propio ajuste (una variable de entorno detrás de un valor de configuración, por ejemplo). Excluye esta ruta de la protección CSRF de tu aplicación, y responde rápido: procesa la notificación en un job si requiere trabajo.