Ir al contenido
Quiet Social

Webhooks

Esta documentación está traducida del francés. Si ambas versiones difieren, prevalece la versión francesa.

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 de X-Social-Timestamp y 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.