- Documentación
- API · Versión 1.0
- Webhooks
Webhooks
En esta página
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, conRetry-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
301o un302cuenta 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-Deliveryes 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.