Black Friday50% de descuento y créditos dobles en el anualVer la oferta

Documentación · Automarticles

Documentación de Webhooks

Aprende a recibir los posts y las categorías de Automarticles en tu propio sistema.

En esta página

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:

  1. En Configuración › Integraciones › Webhook, completa el campo URL del Webhook con la dirección que va a recibir los eventos y guarda.
  2. Haz clic en Verificar. Enviamos un POST a tu URL con el token en la cabecera access-token y el cuerpo de abajo.
  3. Tu endpoint tiene que responder con estado 2xx y un JSON que devuelva exactamente el mismo token que recibió.
  4. Con el token devuelto igual al enviado, la integración queda verificada y puedes encender la opción Enviar webhooks.
Cuerpo que enviamos
{
  "event": "CHECK_INTEGRATION"
}
Respuesta esperada
{
  "token": "SEU_TOKEN_AQUI"
}
Los eventos solo se envían con la integración verificada y el envío activado. Al generar un token nuevo, la verificación y el envío se apagan: actualiza el token en tu sistema y verifica de nuevo.

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: draft cuando es borrador, future cuando está programado y publish cuando 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: usa content.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. null cuando 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. null mientras el post no tiene fecha.
Ejemplo
{
  "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
}
Post sin categoría
{
  "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.

Respuesta recomendada
{
  "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.
Ejemplo
{
  "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 POST con Content-Type: application/json y la cabecera access-token.
  • Responde con un estado 2xx en 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 http o https, 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.

¿Tienes dudas?

Escríbenos al correo

contato@automarticles.com