Ir al contenido
Quiet Social

Webhooks

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

Un webhook avisa a tu aplicación cuando una publicación cambia de estado, sin que tenga que consultar la API. Quiet Social envía una petición POST firmada a la dirección que declares.

Los endpoints se declaran mediante la API, con el permiso webhooks:manage, o desde el panel, menú Webhooks (consulta la guía). Ambas vías llevan al mismo endpoint, con las mismas reglas.

Declarar un endpoint: POST /webhooks

Campo Tipo Requerido Nota
url texto (2048) sí En https, accesible desde internet.
events lista sí Al menos un evento del catálogo.
brand_id brd_… no Limita el endpoint a los eventos de una marca. Si falta, cubre todo el espacio de trabajo.
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
}

Guarda secret ahora. Solo se devuelve en la creación: ninguna lectura posterior lo muestra. Perderlo obliga a eliminar el endpoint y declarar uno nuevo.

La dirección se comprueba desde la declaración. Se rechazan, con 422 sobre el campo url y el motivo exacto:

  • cualquier esquema distinto de https;
  • los nombres reservados a la máquina o a la red local (localhost, .local, .internal, un nombre sin punto…);
  • las direcciones privadas o reservadas, y todo nombre cuya resolución DNS lleve a una dirección así.

Un cliente vinculado a una marca siempre declara endpoints de su marca. Un cliente de espacio que envía brand_id debe designar una marca de su espacio; si no, la declaración se rechaza con 422 en el campo brand_id. GET /brands da los identificadores válidos.

Códigos: 201, 401, 403, 422, 429.

Listar: GET /webhooks

Los endpoints visibles para el cliente, en el orden de su creación, sin paginación. Un cliente vinculado a una marca ve los endpoints de esa marca y los que cubren todo el espacio. Lee estos últimos, pero no los modifica, ni los elimina, ni los prueba: esas tres rutas le responden 403 con endpoint_shared.

secret no aparece. El estado de salud, sí: status vale active o suspended, failure_count cuenta las entregas fallidas consecutivas, last_success_at y last_failure_at fechan los últimos resultados.

Códigos: 200, 401, 403, 429.

Modificar: PATCH /webhooks/{id}

Cambia la dirección, la lista de eventos, o ambas. Un campo ausente queda tal cual. La dirección se comprueba igual que en la declaración.

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, con el endpoint releído, sin secret. La marca de un endpoint y su status no se modifican.

Códigos: 200, 401, 403, 404, 422, 429.

Eliminar: DELETE /webhooks/{id}

204 No Content. La eliminación es definitiva.

Códigos: 204, 401, 403, 404, 429.

Probar: POST /webhooks/{id}/test

Envía una notificación de control, exactamente por el mismo camino que una real: misma firma, mismas cabeceras, mismos reintentos.

{
  "data": {
    "delivery_id": "whd_01k4b91b8y2z3a4c5d6e7f8g9h",
    "status": "pending"
  }
}

202 Accepted: la entrega se pone en cola, todavía no ha tenido lugar. Su resultado se constata en tu endpoint, o en last_success_at y last_failure_at.

El evento es webhook.test, fuera del catálogo: tu endpoint lo recibe aunque no se haya suscrito a él. No lo hagas caer en una rama de error «evento desconocido». Su cuerpo:

{
  "message": "This is a check notification sent from Quiet Social.",
  "sent_at": "2026-10-01T09:21:03+00:00"
}

Dos rechazos:

  • un endpoint suspendido no recibe nada: 409 endpoint_suspended, « This endpoint is suspended and receives nothing: reactivate it first. » (este endpoint está suspendido y no recibe nada: reactívalo primero);
  • cada prueba sale realmente hacia tu dirección: 5 por minuto y por endpoint como máximo, panel y API en conjunto. Por encima, 429 too_many_requests, con Retry-After.

Códigos: 202, 401, 403, 404, 409, 429.

Catálogo de eventos

Evento Se emite cuando
publication.created Se crea una publicación, desde la API o desde el panel.
publication.approved Se valida una publicación sometida a validación, por el equipo o por el cliente.
publication.scheduled Una publicación pasa a scheduled: liberada por publish, o relanzada por retry después de haber terminado.
publication.processing Al menos un objetivo ha salido y otro todavía no ha llegado a término.
publication.published Todos los objetivos están publicados.
publication.partially_published Todos los objetivos tienen un resultado, y solo una parte está publicada.
publication.failed Todos los objetivos tienen un resultado, y ninguno está publicado.
publication.cancelled Todos los objetivos están cancelados.
publication_target.published Se publica un objetivo.
publication_target.failed Un objetivo falla, o pasa a requires_reconnect: desde tu punto de vista, la entrega no tendrá lugar sin intervención.
social_connection.requires_reconnect Una conexión deja de poder publicar: su acceso ha caducado, ha sido revocado, o la red lo ha rechazado. Se emite una vez, en el cambio; no en cada comprobación mientras siga pendiente de restablecer.
destination.disabled Un destino activo deja de estarlo: desactivado por un miembro del equipo, o convertido en inaccesible.

Un endpoint limitado a una marca solo recibe los eventos de esa marca. Una conexión pertenece al espacio de trabajo y no a una marca: el endpoint de una marca solo se entera de social_connection.requires_reconnect si la conexión sostiene destinos de esa marca, y recibe entonces un cuerpo reducido (consulta más abajo).

Lo que recibe tu 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
Cabecera Contenido
X-Social-Event El nombre del evento. No se repite en el cuerpo.
X-Social-Delivery El identificador whd_… de la entrega, el mismo en cada intento.
X-Social-Timestamp La marca de tiempo Unix de la firma, recalculada en cada intento.
X-Social-Signature HMAC-SHA256(timestamp + "." + cuerpo en bruto, secret), en hexadecimal.

Para un evento publication.*, el cuerpo lleva la publicación, exactamente como la devuelve GET /publications/{id}:

{
  "publication": {
    "id": "pub_01k4b8y5t2v9h6p8w0y2z4b6c8",
    "status": "published",
    "external_reference": "article-42",
    "targets": ["…"]
  }
}

Para un evento publication_target.*, lleva el objetivo, exactamente como en targets[], y el identificador de su publicación:

{
  "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"
}

Estos dos ejemplos están abreviados: los campos son todos los descritos en Publicaciones.

Para destination.disabled, el cuerpo lleva el destino, exactamente como lo devuelve GET /destinations/{id}:

{
  "destination": {
    "id": "dst_01k4b8x2q9r7f3m5t6v8w0y2z4",
    "network": "facebook",
    "name": "Fabrique du Nord",
    "status": "disabled",
    "can_publish": false,
    "capabilities": {"…": "…"}
  }
}

Para social_connection.requires_reconnect, lleva la conexión y sus destinos:

{
  "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 vale expired, revoked o requires_reconnect. Un endpoint limitado a una marca recibe un cuerpo reducido: ni account ni error_message, y solo los destinos de su marca. La conexión no tiene identificador público; restablécela desde el panel.

Verificar la firma

Verifica la firma sobre el cuerpo en bruto, antes de cualquier decodificación JSON: un cuerpo decodificado y luego vuelto a codificar ya no tiene los mismos bytes. Rechaza una marca de tiempo demasiado antigua — cinco minutos es un buen margen — para que una petición interceptada no pueda repetirse.

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);

    // Una misma entrega puede llegar dos veces: ignora un X-Social-Delivery ya procesado.
    // …

    return response()->noContent();
});

Excluye esta ruta de la protección CSRF de tu aplicación.

Entrega y reintentos

  • Una entrega tiene éxito cuando tu endpoint responde con un estado 2xx. Responde rápido y procesa después: la petición se abandona al cabo de 10 segundos, y la conexión al cabo de 5.
  • Las redirecciones no se siguen. Un 301 o un 302 cuenta como un fallo: declara la dirección final.
  • Una entrega fallida se reintenta, hasta seis intentos en total, tras 1 minuto, 5 minutos, 30 minutos, 2 horas y luego 6 horas.
  • Una misma entrega puede llegar más de una vez. X-Social-Delivery es estable de un intento a otro: úsalo para ignorar un duplicado.

Suspensión

Tras 10 entregas consecutivas fallidas (cada una después de todos sus intentos), el endpoint pasa a suspended y ya no recibe nada. Una entrega con éxito pone el contador a cero.

Un endpoint cuya dirección resulta estar prohibida en el momento del envío — un nombre que ahora apunta a una dirección privada, por ejemplo — se suspende inmediatamente.

Un endpoint suspendido no se reactiva mediante la API. Corrige la causa y usa Réactiver (Reactivar) en el panel, menú Webhooks: la dirección se comprueba de nuevo, el contador de fallos vuelve a cero y el secreto no cambia. Una dirección que sigue llevando a un destino prohibido impide la reactivación.