Cómo usar webhooks en Postoria
Los webhooks de Postoria envían los resultados de los intentos de publicación completados a un endpoint HTTPS público que tú controlas. Úsalos para actualizar un registro interno, guardar los enlaces publicados en tu CMS o iniciar un flujo de trabajo cuando finalice un intento de publicación.
Los webhooks están disponibles en todos los planes, incluido Free. Funcionan tanto con las publicaciones creadas en la aplicación de Postoria como con las creadas a través de integraciones.
Antes de empezar
- Puedes configurar una URL de webhook por perfil. Recibe los eventos seleccionados de todos los espacios de trabajo de los que eres propietario, incluidos los que no estés viendo en ese momento.
- No se incluyen los espacios de trabajo en los que solo eres miembro del equipo. Su propietario gestiona la configuración de webhooks de esos espacios.
- Tu receptor debe aceptar solicitudes HTTP
POSTen una URL HTTPS accesible públicamente. - La URL puede contener hasta 2048 caracteres y no debe incluir un nombre de usuario, una contraseña ni un fragmento de URL como
#section. Postoria no sigue redirecciones, así que introduce la URL de destino final. - No necesitas una clave de la API pública para recibir webhooks. El uso de la API pública, el servidor MCP o la integración de Postoria con n8n sigue requiriendo Pro o Agency.
Configura tu webhook
- Abre Configuración, busca Webhooks y haz clic en Configurar.
- Introduce la dirección de tu receptor en URL del webhook.
- Activa Activar webhooks.
- En Eventos que quieres recibir, selecciona Publicación completada correctamente, Error al publicar o ambos. Debes seleccionar al menos un evento mientras los webhooks estén activados.
- Haz clic en Guardar. El diálogo se cierra y la sección Webhooks muestra Activado y la URL guardada.
- En la sección Webhooks, busca Secreto de firma. Su valor está oculto de forma predeterminada. Usa el botón para mostrarlo o copiarlo y configura la verificación de firmas en tu receptor.
Mantén privado el secreto de firma. Permite que tu receptor verifique que Postoria ha firmado una solicitud para tu perfil.
Cuando el receptor esté listo, publica contenido y consulta el Historial de webhooks para confirmar que el evento ha llegado. Al activar los webhooks, no se envían eventos de publicaciones cuyo proceso de publicación ya había finalizado.
Elige los eventos que necesitas
Un evento describe el intento de publicación completado de una publicación. Postoria espera a que finalicen las publicaciones en todos los destinos seleccionados antes de comunicar el resultado global.
| Evento | Ajuste | Significado |
|---|---|---|
post.succeeded | Publicación completada correctamente | La publicación se completó correctamente en todos los destinos seleccionados. |
post.failed | Error al publicar | El proceso de publicación finalizó con un fallo, incluidos los casos en los que se publicó correctamente en algunos destinos y se produjo un error en otros. |
Por ejemplo, si una publicación se publica correctamente en una cuenta y falla en otra, el evento es post.failed. Revisa los resultados individuales antes de decidir qué reintentar: la publicación que se completó correctamente ya está publicada.
Estos eventos cubren los intentos de publicación completados. No informan de si los archivos multimedia están listos, de actualizaciones de analíticas ni de actividad en la bandeja de entrada. Una solicitud de programación rechazada o un error que impida iniciar la publicación no genera un webhook con el resultado de publicación. Comprueba por separado las publicaciones que nunca llegan a tener un resultado final.
Lee el cuerpo del mensaje
Postoria envía JSON con Content-Type: application/json; charset=utf-8. Este ejemplo muestra una publicación con un resultado correcto y otro fallido:
{
"id": "evt_7c7b19fd634441f3a0b460f2dc7e6812",
"type": "post.failed",
"occurred_at": "2026-11-15T12:00:00Z",
"workspace_id": 42,
"data": {
"post_id": 1234,
"results": [
{
"account_id": 101,
"link_to_post": "https://example.com/published-post",
"error": null
},
{
"account_id": 102,
"link_to_post": null,
"error": "The social account needs to be reconnected."
}
]
}
}
Los ID, el enlace y el error anteriores son ejemplos ilustrativos.
ididentifica el evento y no cambia entre intentos de entrega.typeespost.succeededopost.failed.occurred_ates la fecha y hora UTC en la que Postoria registró el resultado final de publicación, no la del último intento de entrega.workspace_ididentifica el espacio de trabajo. Úsalo para dirigir los eventos al espacio correspondiente si tu receptor atiende a varios espacios de trabajo.data.post_ides el ID de la publicación en Postoria.data.resultscontiene los resultados de publicación con el ID de una cuenta social, el enlace de la publicación cuando esté disponible y un error cuando corresponda. Tantolink_to_postcomoerrorpueden sernull.
Los resultados utilizan los mismos campos que los resultados de publicación de la API pública. Una cuenta puede aparecer más de una vez, por ejemplo, cuando una publicación contiene varias historias. No des por hecho que hay exactamente un resultado por cuenta.
Verifica la firma
Cada solicitud incluye tres cabeceras:
| Cabecera | Valor |
|---|---|
webhook-id | El ID del evento, que coincide con id en el cuerpo del mensaje. |
webhook-timestamp | La marca de tiempo Unix en segundos de este intento de entrega. |
webhook-signature | v1, seguido de una firma HMAC-SHA256 codificada en Base64. |
Para verificar una solicitud:
-
Lee el cuerpo de la solicitud sin procesar antes de analizar el JSON. Analizarlo y volver a serializarlo puede cambiar los bytes e invalidar la firma.
-
Elimina el prefijo
whsec_del secreto de firma y decodifica el valor restante de Base64 para obtener la clave de firma. -
Une la cabecera
webhook-id, la cabecerawebhook-timestampy el cuerpo sin procesar, en ese orden, con un punto literal entre cada parte:webhook-id.webhook-timestamp.raw-request-body -
Calcula el HMAC-SHA256 de los bytes UTF-8 de esa cadena con la clave de firma decodificada y codifica el resultado en Base64.
-
Compara el resultado con el valor que aparece después de
v1,enwebhook-signaturemediante una comparación en tiempo constante. -
Comprueba que la marca de tiempo firmada esté dentro del margen de tolerancia de reloj de tu receptor para limitar la reutilización de solicitudes antiguas. Usa la marca de tiempo de la cabecera para esta comprobación, ya que los reintentos pueden llegar mucho después de
occurred_at.
Rechaza las solicitudes con cabeceras de firma ausentes o no válidas antes de actuar sobre su contenido. Usa webhook-id para reconocer los eventos que tu receptor ya ha procesado.
Responde a tiempo y gestiona los reintentos
Devuelve una respuesta HTTP 2xx en un plazo de 10 segundos para confirmar la entrega. Una forma práctica de implementar el receptor consiste en verificar la solicitud, almacenar el evento y su ID de forma persistente y, después, devolver la respuesta. Las tareas posteriores que requieran más tiempo pueden ejecutarse por separado tras esa confirmación.
Postoria pone en cola la entrega inicial en cuanto registra el resultado de publicación. Las respuestas que no sean 2xx, los tiempos de espera agotados y los fallos de conexión provocan reintentos automáticos. Las respuestas de redirección también cuentan como intentos de entrega fallidos.
Los reintentos se programan para cuando hayan transcurrido 5, 15 y 30 minutos, y después 1, 3, 6, 12 y 24 horas desde el primer intento. Estos plazos se cuentan desde el primer intento, no desde el anterior. La entrega real puede producirse más tarde si el procesamiento se retrasa. El calendario permite hasta nueve intentos, incluido el inicial.
El ID del evento y el cuerpo JSON no cambian entre reintentos. Cada intento recibe una nueva marca de tiempo de envío y una firma calculada para ese intento. Puede haber entregas duplicadas, así que asegúrate de que procesar el mismo evento varias veces sea seguro. No des por hecho que los distintos eventos llegan en el orden de publicación.
Reintentar un webhook solo vuelve a intentar entregar el resultado. No publica de nuevo el contenido.
Consulta el historial de entregas
Abre Configuración → Webhooks → Historial de webhooks o ve directamente al Historial de webhooks.
El historial incluye los espacios de trabajo de los que eres propietario y se conserva durante 30 días. Cada fila muestra el evento, el ID de la publicación, el ID del espacio de trabajo, el estado de entrega, el número de intentos y el último estado HTTP. Expande una fila para ver el ID del mensaje, las fechas y horas de los intentos, la fecha y hora de entrega, el error si lo hay y el cuerpo JSON.
| Estado de entrega | Significado |
|---|---|
| En espera | El mensaje está esperando su primera entrega o un reintento. |
| Enviando | Hay un intento de entrega en curso. |
| Entregado | Tu receptor devolvió una respuesta HTTP de éxito. |
| Fallido | Los intentos de entrega finalizaron sin una respuesta HTTP de éxito. |
El estado de entrega y el resultado de publicación son distintos. Un evento post.failed puede tener el estado Entregado: se produjo un fallo al publicar, pero tu receptor recibió correctamente esa información.
Recarga la página para ver los estados de entrega más recientes y usa Cargar más para ver mensajes anteriores. Si la carga falla, Reintentar vuelve a cargar el historial. Estas acciones no reenvían webhooks.
Cambia la URL o desactiva los webhooks
En Configuración → Webhooks, haz clic en Configurar, actualiza la URL o desactiva Activar webhooks y haz clic en Guardar. El cambio afecta a los eventos que se creen a partir de ese momento.
Si cierras el diálogo de configuración sin hacer clic en Guardar, se descartan tus cambios.
Cuando los webhooks están desactivados, la sección Webhooks muestra Desactivado y oculta la URL guardada y el secreto de firma. Haz clic en Configurar para editar la URL o volver a activar los webhooks.
Los eventos ya registrados conservan su URL de destino original y pueden seguir reintentando la entrega. Desactivar los webhooks no cancela esas entregas pendientes, y cambiar la URL no las redirige a la nueva dirección.
Solución de problemas
- La configuración no se guarda: comprueba que la URL use HTTPS, sea pública, no contenga credenciales integradas ni fragmento y respete el límite de longitud. Selecciona al menos un evento al activar los webhooks.
- No aparece ningún evento: comprueba que los webhooks estuvieran activados antes de que finalizara la publicación, que el evento correspondiente estuviera seleccionado y que seas el propietario del espacio de trabajo. Los errores anteriores al inicio de la publicación quedan fuera de estos eventos.
- La entrega sigue fallando: revisa el último estado HTTP y el error en el Historial de webhooks. Comprueba que el endpoint sea accesible directamente, tenga un certificado HTTPS válido, acepte
POSTy devuelva2xxen un plazo de 10 segundos. - La verificación de la firma falla: usa el cuerpo sin procesar, decodifica el secreto de Base64 después de eliminar
whsec_e incluye los valores exactos de las cabeceras y los puntos de separación en la cadena firmada. - El mismo evento vuelve a llegar: elimina los duplicados por ID de evento, no por ID de publicación. Un intento posterior de publicar la misma publicación puede generar un evento diferente.