Introducción
Esta documentación describe cómo usar los webhooks de Automarticles para automatizar tu blog. En cada evento de post o de categoría, Automarticles envía una solicitud POST con un cuerpo JSON a la URL que configures, y tu sistema decide qué hacer con ella: crear el post, actualizarlo, despublicarlo, eliminarlo.
El nombre del evento viene siempre en el campo event del cuerpo. Son siete: CHECK_INTEGRATION, POST_CREATED, POST_UPDATED, POST_DELETED, CATEGORY_CREATED, CATEGORY_UPDATED y CATEGORY_DELETED.
Autenticación
Toda solicitud de webhook lleva un token de acceso en la cabecera access-token. Encuentras ese token en Automarticles, en Configuración › Integraciones › Webhook, en el campo Token de Autenticación.
En tu endpoint, compara el valor de la cabecera con tu token antes de procesar cualquier cosa, y rechaza (401) la solicitud que llegue sin él o con un valor distinto.
Antes de activar el envío y empezar a recibir los eventos, tienes que verificar la integración con el procedimiento siguiente.
2.1Evento CHECK_INTEGRATION
CHECK_INTEGRATION es la prueba inicial: confirma que Automarticles puede hablar con tu sistema y que el token está siendo reconocido. Paso a paso:
- En Configuración › Integraciones › Webhook, completa el campo URL del Webhook con la dirección que va a recibir los eventos y guarda.
- Haz clic en Verificar. Enviamos un
POSTa tu URL con el token en la cabeceraaccess-tokeny el cuerpo de abajo. - Tu endpoint tiene que responder con estado
2xxy un JSON que devuelva exactamente el mismo token que recibió. - Con el token devuelto igual al enviado, la integración queda verificada y puedes encender la opción Enviar webhooks.
{
"event": "CHECK_INTEGRATION"
}{
"token": "SEU_TOKEN_AQUI"
}Post
Automarticles envía tres eventos de post: POST_CREATED, POST_UPDATED y POST_DELETED.
3.1Objeto Post
idstring- Identificador único del post. Guárdalo en tu base de datos: por él llegan las actualizaciones y la eliminación. Trátalo como texto, sin suponer un formato.
slugstring- Versión amigable del título, usada para armar la URL del post.
statusenum- Estado del post:
draftcuando es borrador,futurecuando está programado ypublishcuando está publicado. titlestring- Título del post.
contentobject- El contenido del post en más de un formato.
content.textstring- Contenido en texto plano, sin formato, con un salto de línea entre los bloques.
content.htmlstring- Contenido con formato HTML.
content.richnull- Campo heredado (Rich Text). Hoy es siempre
null: usacontent.html.
descriptionstring- Descripción breve del post (la meta description).
featured_imageobject- La imagen destacada del post.
featured_image.urlstring | null- URL de la imagen.
nullcuando el post no tiene imagen. featured_image.filenamestring | null- Nombre del archivo de la imagen.
featured_image.alt_textstring- Texto alternativo de la imagen, usado para accesibilidad.
categoryobject- La categoría del post. Cuando el post no tiene categoría, el objeto viene con los dos campos vacíos (nunca
null).category.idstring- Identificador único de la categoría.
category.namestring- Nombre de la categoría.
publication_datetimestamp | null- Fecha de publicación (o de la programación) en UNIX, en segundos.
nullmientras el post no tiene fecha.
{
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "draft",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}{
"category": {
"id": "",
"name": ""
}
}3.2Evento POST_CREATED
Se envía cuando se crea un post en la plataforma, todavía como borrador. Un borrador totalmente vacío (sin título y sin texto) no se envía.
{
"event": "POST_CREATED",
"post": {
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "draft",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}
}3.3Evento POST_UPDATED
Se envía cuando un post cambia. Vale para el contenido y también para estado, programación, imagen, categoría y los demás datos. Por este evento te enteras de que un post se publicó (status pasa a publish) o volvió a borrador.
Trata POST_UPDATED como “crear o actualizar”: si el post.id todavía no existe de tu lado, crea el post.
{
"event": "POST_UPDATED",
"post": {
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "publish",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}
}3.4Evento POST_DELETED
Se envía cuando se elimina un post de la plataforma. Lleva solo el id.
{
"event": "POST_DELETED",
"post": {
"id": "1700496185550x505140687844954560"
}
}3.5Respuesta con la URL del post
Opcional, y recomendado: al responder un POST_CREATED o POST_UPDATED, devuelve la URL pública del post. Automarticles guarda esa dirección y la usa como el enlace del post.
{
"post": {
"url": "https://seusite.com/blog/slug-do-post"
}
}Categoría
Automarticles envía tres eventos de categoría: CATEGORY_CREATED, CATEGORY_UPDATED y CATEGORY_DELETED.
4.1Objeto Category
idstring- Identificador único de la categoría. Guárdalo en tu base de datos: por él llegan las actualizaciones y la eliminación.
namestring- Nombre de la categoría en el blog.
{
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}4.2Evento CATEGORY_CREATED
Se envía cuando se crea una categoría en la plataforma.
{
"event": "CATEGORY_CREATED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}
}4.3Evento CATEGORY_UPDATED
Se envía cuando se modifica una categoría en la plataforma.
{
"event": "CATEGORY_UPDATED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}
}4.4Evento CATEGORY_DELETED
Se envía cuando se elimina una categoría en la plataforma. El objeto replace_to es opcional: cuando viene, trae la categoría que pasa a recibir los posts de la eliminada. Sin él, esos posts quedan sin categoría.
{
"event": "CATEGORY_DELETED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Categoria excluída"
},
"replace_to": {
"id": "1700480211667x178676794280218533",
"name": "Nova categoria"
}
}Entrega y registros
- Cada evento es un
POSTconContent-Type: application/jsony la cabeceraaccess-token. - Responde con un estado
2xxen hasta 15 segundos. Cualquier otro estado, o la falta de respuesta en ese plazo, cuenta como fallo. - No hay reenvío automático. Toda entrega, con éxito o con fallo, queda registrada en Configuración › Integraciones › Webhook › Registros de envío, con el cuerpo enviado y la respuesta recibida, y se puede reenviar desde ahí con el botón Reenviar.
- La URL tiene que ser pública, en
httpohttps, y sin usuario y contraseña en la dirección. Las direcciones de red interna se rechazan. Las redirecciones se siguen (hasta tres). - Como un mismo post puede generar varios eventos, haz que tu endpoint grabe por
id(crear si no existe, actualizar si existe), para que recibir el mismo evento dos veces no duplique nada.