Ir al contenido
Quiet Social

Webhooks

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

Con un secreto de firma, el paquete registra una ruta que recibe las notificaciones de Quiet Social, verifica cada una, mantiene al día el estado de tus posts y emite los eventos de Laravel correspondientes.

La ruta

Rellena QUIET_SOCIAL_WEBHOOK_SECRET y el paquete registra POST /social/webhook (la clave webhook_path), con el nombre social.webhook. Sin secreto, la ruta no existe: una ruta que aceptara cuerpos sin firmar dejaría que cualquiera inventara el estado de tus publicaciones. Está fuera del grupo de middlewares web: ni sesión, ni token CSRF.

Declara su dirección en el panel de Quiet Social, página Webhooks: una dirección en https accesible desde Internet, con los eventos deseados. El secreto (whsec_…) se muestra una sola vez, al declarar el webhook. El recorrido se describe en la guía, y el contenido de cada notificación en la referencia de los webhooks.

La firma

El SDK verifica cada petición sobre el cuerpo en bruto, dentro de la tolerancia de webhook_tolerance segundos (300 por defecto). Una firma ausente, falsa o caducada responde 401, y no se da nada por cierto. Demasiado amplia, la tolerancia permite reproducir una llamada interceptada; demasiado estrecha, falla en cuanto un reloj se desvía.

Los duplicados

  • Reintentos. Un reintento de la API, firmado de nuevo con una nueva marca de tiempo, se reconoce por su X-Social-Delivery, su evento y su cuerpo durante webhook_replay_window segundos. Las 12 horas por defecto cubren todo el calendario de reintentos de la API (6 intentos, a lo largo de unas 8 h 36 min).
  • Reproducción. La misma petición firmada, reproducida con otro identificador de entrega, se reconoce por su firma durante el doble de la tolerancia.
  • Fallo del procesamiento. Una entrega cuyo procesamiento lanza una excepción se olvida, para que el siguiente reintento pase.

Estas entregas viven en tu caché por defecto, que debe estar compartida por todos los servidores web: sin eso, un servidor no reconoce lo que otro ya ha procesado.

El orden y los estados

  • El vínculo de la publicación se actualiza antes de que se emita el evento.
  • Un estado no final nunca sustituye a un estado final, salvo una publicación fallida relanzada desde el panel, que vuelve a abrir su vínculo.
  • Una notificación que llega antes del vínculo de un post recién creado se guarda unos minutos, y se aplica en cuanto se escribe el vínculo.
  • Una publicación cancelada o fallida en Quiet Social cierra el vínculo automático que la seguía.

Las respuestas

Cada notificación firmada se confirma con 204, incluidos:

  • los eventos que el paquete no transmite (publication.scheduled, publication.processing…), que aun así actualizan el vínculo de su publicación;
  • un evento contradicho por el estado de su cuerpo firmado (publication.failed sobre una publicación publicada), que se registra en el log y no emite nada.

Un error haría que la API reintentara, y luego suspendiera el endpoint tras fallos repetidos.