Webhooks

¿No tienes una integración nativa de Sorank para tu CMS? El conector Webhook te permite enviar tus artículos generados a cualquier URL, Zapier, Make, n8n o un endpoint personalizado en tu propio sitio web programado, de modo que puedas publicar tu contenido donde lo necesites.

Cómo funciona

Cuando publicas un artículo en Sorank, enviamos una solicitud POST con una carga útil JSON estructurada a la URL que configuraste. Tu endpoint o herramienta de automatización puede entonces procesar la carga útil y crear la publicación en tu blog, sitio web personalizado o cualquier otra herramienta que acepte solicitudes HTTP entrantes.

⚠️ Importante: el webhook solo envía los datos, tú los publicas

Esto es lo más importante que debes entender sobre el conector Webhook. Por nuestra parte, Sorank empaqueta todo lo que necesitas dentro del JSON (título, slug, cuerpo HTML completo, meta descripción, imágenes, idioma y más) y lo dispara hacia tu URL. En cuanto ese JSON se envía correctamente, Sorank marca la entrega como exitosa.

Ese estado de "éxito" solo confirma una cosa: los datos salieron de Sorank y tu endpoint los aceptó. No tenemos forma de saber qué ocurre después en tu lado. No podemos detectar si tu código realmente leyó el JSON, mapeó los campos correctamente o publicó el artículo en tu sitio web.

Dicho de otro modo, el webhook es solo un mecanismo de entrega para los datos. Recibirlo, analizarlo y publicarlo en tu CMS es enteramente tu responsabilidad. Si el artículo no aparece en tu blog aunque Sorank muestre "éxito", el problema casi siempre está en cómo tu integración captura y gestiona la carga útil, no en la entrega en sí.

Paso 1: Abre la integración Webhook

1. Haz clic en tu foto de perfil en la esquina superior derecha y selecciona Ajustes.
2. Abre la pestaña Integraciones.
3. Desplázate hasta la tarjeta Webhook y haz clic en Conectar tu sitio web.

Paso 2: Configura tu endpoint

1. Pega tu URL de destino en el campo URL del Webhook (por ejemplo, un catch hook de Zapier, un webhook de Make o el endpoint de tu propio servidor).
2. Opcionalmente, añade un token secreto si tu endpoint requiere autenticación. Sorank lo incluirá como token Bearer en la cabecera Authorization para que tu servidor pueda verificar que la llamada proviene de Sorank.
3. Haz clic en Test para enviar una carga útil de muestra (tipo de evento webhook.test) y confirmar que tu endpoint responde correctamente.
4. Haz clic en Save webhook para activar la integración.

Detalles de la solicitud HTTP

Cada webhook que Sorank envía a tu endpoint sigue el mismo contrato HTTP. Esto es lo que recibirá tu servidor:

• Método: POST
• Content-Type: application/json
• User-Agent: SORANK-Webhook/1.0
• Authorization: Bearer {webhook_secret} (opcional, solo se envía si configuraste un secreto en los ajustes de tu integración)

Usa la cabecera User-Agent para identificar el tráfico de Sorank en tus registros, y verifica la cabecera Authorization por tu parte para asegurarte de que la solicitud proviene de Sorank y no de un origen desconocido.

Estructura de la carga útil del webhook

Sorank emite dos tipos de eventos de webhook. Ambos comparten el mismo sobre de nivel superior (event, delivery_id, timestamp, article), de modo que tu integración solo necesita actuar según el campo event para enrutar la carga útil.

Evento: article.published

Se dispara cada vez que publicas un artículo desde Sorank. Este es el evento que tu endpoint de producción debe procesar para crear la publicación en tu CMS o activar tu flujo de automatización.

{
  "event": "article.published",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Best SEO Practices for 2025",
    "slug": "best-seo-practices-2025",
    "meta_description": "Discover the best SEO practices for 2025.",
    "focus_keyphrase": "seo practices",
    "content": "<h1>Best SEO Practices</h1><p>Article body content here...</p>",
    "featured_image": {
      "url": "https://storage.example.com/image.jpg",
      "alt": "Best SEO Practices for 2025",
      "placement": "hero"
    },
    "images": [
      {
        "url": "https://storage.example.com/image2.jpg",
        "alt": "SEO diagram",
        "placement": "body"
      }
    ],
    "word_count": 1500,
    "keyword": "seo practices",
    "language": "en-US"
  }
}

‍


Evento: webhook.test

Se dispara cuando haces clic en el botón Test en Sorank para verificar que tu endpoint es accesible. La carga útil usa valores ficticios (id son todo ceros, featured_image se omite, images está vacío) para que tu integración pueda ignorarlo de forma segura o usarlo para confirmar la conectividad sin crear una publicación real.

{

  "event": "webhook.test",

  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",

  "timestamp": "2025-05-21T10:30:45.123456Z",

  "article": {

    "id": "00000000-0000-0000-0000-000000000000",

    "title": "Test Article - Webhook Connectivity Check",

    "slug": "test-article-webhook-check",

    "meta_description": "This is a test payload to verify webhook connectivity.",

    "focus_keyphrase": "webhook test",

    "content": "<h2>Test Article</h2><p>This is a test payload sent by SORANK to verify your webhook endpoint is working correctly.</p>",

    "images": [],

    "word_count": 20,

    "keyword": "webhook test",

    "language": "en-US"

  }

}

Referencia de campos

• event, tipo de evento. Puede ser article.published o webhook.test. Actúa según este campo para enrutar la carga útil.
• delivery_id, UUID único para cada intento de entrega. Guárdalo por tu parte para deduplicar reintentos y protegerte contra publicaciones duplicadas.
• timestamp, marca de tiempo ISO 8601 UTC del momento en que se emitió el evento.
• article.id, identificador único del artículo en Sorank.
• article.title, el H1 / título del artículo.
• article.slug, slug compatible con URL, en minúsculas y con guiones.
• article.meta_description, meta descripción SEO, lista para insertar en tu etiqueta <meta name="description">.
• article.focus_keyphrase, frase clave objetivo principal usada para el artículo.
• article.content, cuerpo completo del artículo en HTML, incluyendo encabezados, párrafos, listas y etiquetas de imagen en línea.
• article.featured_image, objeto de imagen de portada con url, alt y placement. Solo presente en eventos article.published.
• article.images, array de imágenes adicionales en el cuerpo. Cada entrada tiene url, alt y placement. Puede estar vacío.
• article.word_count, recuento total de palabras del cuerpo del artículo.
• article.keyword, igual que la frase clave objetivo, mantenida como campo separado para integraciones compatibles con versiones anteriores.
• article.language, etiqueta de idioma BCP 47 (p. ej. en-US, fr-FR).

Casos de uso comunes

• Zapier: usa un disparador "Catch Hook" para reenviar artículos a miles de aplicaciones como WordPress, Notion, Airtable o Google Sheets.
• Make: usa un módulo de Webhooks para crear automatizaciones de publicación personalizadas de varios pasos.
• n8n: conecta un nodo Webhook a un flujo que cree la publicación en tu CMS headless o back office.
• Backend personalizado: envía artículos directamente a tu propia API para publicar en un sitio programado a mano, un CMS headless como Sanity o Strapi, o cualquier herramienta interna.

Consejos

• Haz clic siempre en Test antes de guardar para confirmar que tu endpoint acepta la solicitud y devuelve una respuesta 2xx.
• Actúa según el campo event del lado del servidor para que las llamadas webhook.test nunca creen publicaciones reales.
• Usa delivery_id como clave de idempotencia para evitar publicar el mismo artículo dos veces en los reintentos.
• Mantén privado tu token secreto, verifica la cabecera Authorization en cada solicitud y rota el secreto con regularidad.
• Usa un endpoint HTTPS para mantener seguros los datos del artículo durante el tránsito.
• Una vez conectado, cada artículo publicado en Sorank se enviará automáticamente a tu URL de webhook.

🔄 Por qué tus artículos pueden no aparecer (causas de fallo)

Como el webhook solo entrega los datos, un "éxito" en Sorank no garantiza que el artículo esté publicado en tu sitio. Cuando algo sale mal, casi siempre es del lado receptor. Estas son las causas más comunes y cómo solucionarlas.

Causas del lado de tu integración

• La clave API de tu CMS es de solo lectura en lugar de lectura y escritura, este es uno de los problemas más frecuentes. Si las credenciales que tu código usa para escribir en tu CMS (Sanity, Strapi, Contentful o cualquier backend headless) solo tienen permisos de visualización / lectura, tu endpoint recibirá el JSON pero fallará silenciosamente al crear la publicación. Genera una clave con acceso de escritura y actualízala en tu integración.
• Tu código recibe el JSON pero nunca lo envía a tu CMS, recibir la carga útil es solo la mitad del trabajo. Asegúrate de que tu endpoint realmente mapee los campos de Sorank y cree la publicación en tu CMS o base de datos. Registra la carga útil entrante y confirma que tu llamada de publicación se ejecuta y tiene éxito.
• El mapeo de campos es incorrecto, si tu código espera nombres de campo distintos a los de la carga útil, la publicación puede crearse vacía o ser rechazada. Verifica que lees article.title, article.slug, article.content, etc., exactamente como se documenta arriba.
• Tu endpoint devuelve 2xx pero lanza un error después, si confirmas la solicitud antes de procesarla de forma asíncrona, un fallo posterior en tu lógica de publicación no será visible para Sorank. Revisa tus propios registros de servidor para detectarlos.

Causas del lado de la entrega

• Tu endpoint de webhook ya no responde (servidor fuera de línea), vuelve a poner tu servidor en línea y verifica que la URL responde con normalidad.
• La URL del webhook cambió pero no se actualizó en Sorank, actualiza la URL en los ajustes de integración de Sorank.
• Regeneraste tu secreto de webhook por tu parte, actualiza el secreto en Sorank para que coincida con el que tu servidor ahora espera en la cabecera Authorization.
• Tu endpoint devuelve un error que Sorank no puede interpretar, revisa los registros de tu servidor para identificar el problema y luego corrígelo del lado de tu webhook.
• Un firewall en tu servidor está bloqueando nuestras solicitudes, añade las IP de Sorank a la lista blanca de tu firewall, o permite el User-Agent SORANK-Webhook/1.0.
• Tu endpoint tarda más de 30 segundos en responder, optimiza tu endpoint para que responda más rápido, o confirma la solicitud de inmediato y procésala de forma asíncrona.

Cuando Sorank no puede entregar un artículo a tu endpoint, tu programador se pausa automáticamente y recibirás un correo electrónico. En cuanto corrijas el problema y reconectes tu webhook en Sorank, tu programador se reanuda por sí solo. Tu artículo ya está generado y almacenado de forma segura, no se pierde nada.

🚀 ¿No eres desarrollador? Aloja tu blog en Sorank en su lugar

El webhook requiere que escribas y mantengas código que capture el JSON y lo publique en tu sitio. Si construiste tu sitio con una herramienta no-code o de IA, como Lovable, Base44, Cursor o Claude Code, y no puedes desarrollar y alojar un endpoint que capture el webhook y publique el artículo, hay un camino mucho más sencillo.

Creamos una solución donde puedes autoalojar tu blog en tu propio subdominio, directamente en Sorank. Sin código, sin endpoint que mantener, sin webhook que capturar. Aprende cómo funciona aquí: Aloja tu blog en Sorank.

¿Buscas una integración nativa en su lugar?

Si tu plataforma es compatible, un conector directo es más fácil que el webhook. Consulta nuestras guías para Webflow, Shopify, WordPress.org, WordPress.com, Wix y HubSpot.

¿El problema persiste tras la comprobación?

Si has comprobado los puntos anteriores y la publicación sigue fallando, responde directamente al correo electrónico que recibiste: nuestro equipo investigará qué está ocurriendo en tu cuenta.

Tus artículos permanecen generados y almacenados de forma segura en Sorank. En cuanto se restablezca la conexión, tu programador retoma automáticamente donde lo dejó.