Skip to main content

​
¿Cuándo elegir la publicación por webhook?

El webhook conecta Sorank con un sitio a medida o con una automatización que sabe recibir un artículo y publicarlo. Es la opción adecuada cuando ya dispone de ese sistema de publicación o cuando su equipo puede implementarlo. El funcionamiento consta de tres pasos: Sorank prepara el artículo, lo transmite a su integración y, a continuación, su integración lo publica en su sitio. Una vez configurado este recorrido, puede enviar los artículos desde Sorank o utilizar el calendario para automatizar su generación y envío. Con el contrato de actualización descrito en esta página, también puede enviar una nueva versión al artículo existente. Por ejemplo, una modificación preparada en el editor se envía a su sitio cuando hace clic en Enviar la actualización del artículo. Si desea que Sorank gestione también el alojamiento del blog, elija en su lugar el blog alojado. Si su CMS dispone de un conector nativo, utilice el recorrido presentado en publicar y exportar.

​
Actualizar un webhook existente

Tras actualizar su servidor, Sorank detecta automáticamente la compatibilidad con las actualizaciones en la próxima publicación o reenvío, si su integración todavía se reconoce como legacy. Sorank envía webhook.test; un fallo de detección no impide la entrega habitual. Para activar la detección de inmediato, sin desconectar su webhook:
  1. Abra los ajustes de la integración webhook en Sorank.
  2. Mantenga la misma URL y el mismo secreto.
  3. Haga clic en Guardar.
Su servidor debe responder a webhook.test con un estado HTTP 2xx y este JSON en la raíz:
Esta declaración activa la actualización de los artículos publicados. article_url por sí sola no demuestra que su servidor acepte article.updated. La detección no recupera retroactivamente las URL faltantes: cada publicación completada debe devolver su propia article_url según el contrato que se describe a continuación. ¿No dispone de una integración Sorank nativa para su CMS? El conector Webhook le permite enviar sus artículos generados hacia cualquier URL, Zapier, Make, n8n o un endpoint a medida en su propio sitio desarrollado, para que pueda publicar su contenido donde lo necesite.

​
Cómo funciona

Cuando publica un artículo en Sorank, enviamos una solicitud POST con una carga útil JSON estructurada hacia la URL que ha configurado. Su endpoint o su herramienta de automatización puede entonces procesar la carga útil y crear la publicación en su blog, su sitio a medida o cualquier otra herramienta que acepte solicitudes HTTP entrantes.

​
⚠️ Importante: el webhook solo envía los datos, usted es quien los publica

Esto es lo más importante que debe entender sobre el conector Webhook. Por nuestra parte, Sorank agrupa todo lo que necesita en el JSON (título, slug, cuerpo HTML completo, meta descripción, imágenes, idioma y mucho más) y lo envía hacia su URL. En cuanto ese JSON se envía correctamente, Sorank marca la entrega como exitosa. Este estado de “éxito” confirma una sola cosa: los datos han salido de Sorank y su endpoint los ha aceptado. Un simple acuse de recibo histórico no confirma la publicación. Con el contrato versión 2 que se describe a continuación, una respuesta completada con article_url confirma inmediatamente la publicación en Sorank; su código sigue siendo responsable de la publicación efectiva en su CMS. En otras palabras, el webhook es únicamente un mecanismo de entrega de datos. Recibirlo, analizarlo y publicarlo en su CMS es responsabilidad exclusivamente suya. Si el artículo no aparece a pesar de una entrega exitosa, verifique la recepción, el procesamiento, la publicación y la respuesta devuelta. El estado de entrega por sí solo no permite identificar la causa.

​
Paso 1: abrir la integración Webhook

  1. En el menú lateral, abre Ajustes y después Plataformas de publicación.
  2. Desplázate hasta la tarjeta Webhook y haz clic en Conectar tu sitio web.
Webhooks: Paso 1: abrir la integración Webhook

​
Paso 2: configurar su endpoint

  1. Pegue su URL de destino en el campo Webhook URL (por ejemplo, un catch hook de Zapier, un webhook de Make o el endpoint de su propio servidor).
  2. Si lo desea, añada un Secret token si su endpoint requiere autenticación. Sorank lo incluirá como token Bearer en el encabezado Authorization para que su servidor pueda verificar que la llamada proviene de Sorank.
  3. Haga clic en Test para enviar una carga útil de ejemplo (tipo de evento webhook.test) y confirmar que su endpoint responde correctamente.
  4. Haga clic en Save webhook para activar la integración.
Webhooks: Paso 2: configurar su endpoint

​
Detalles de la solicitud HTTP

Cada webhook que Sorank envía hacia su endpoint sigue el mismo contrato HTTP. Esto es lo que recibirá su servidor:
  • Method: POST
  • Content-Type: application/json
  • User-Agent: SORANK-Webhook/1.0
  • Authorization: Bearer {webhook_secret} (opcional, enviado únicamente si ha configurado un secreto en los ajustes de su integración)
Utilice el encabezado User-Agent para identificar el tráfico de Sorank en sus registros, y verifique el encabezado Authorization en su lado para asegurarse de que la solicitud proviene de Sorank y no de un llamante desconocido.

​
Estructura de la carga útil del webhook

Sorank utiliza tres eventos con el mismo sobre (event, delivery_id, timestamp, article). Una sola ruta POST HTTPS (por ejemplo /sorank-webhook) es suficiente: procese cada valor de event en esa ruta y verifique el token Authorization si ha configurado un secreto.

​
Versión 2: publicar, actualizar y devolver la URL

Para activar la actualización, su ruta debe responder a webhook.test sin crear contenido, con un HTTP 200 y este JSON:
Para article.published, cree el artículo y conserve la asociación entre article.id y su identificador en su CMS. Si esa asociación ya existe, no cree un duplicado. Para article.updated, recupere esa asociación y reemplace el contenido del artículo existente. Si el artículo no se encuentra, devuelva un error, por ejemplo HTTP 404: una actualización nunca debe crear un artículo nuevo. Tras una publicación realmente completada, devuelva HTTP 200 o 201 con:
Tras una actualización completada, utilice "status": "updated" y la URL pública actual. Solo se solicita article_url, no la URL del sitemap. Proporcione una URL HTTPS absoluta en el sitio asociado al perfil de Sorank, no la de su automatización. La respuesta debe ser un objeto JSON de menos de 16 KiB; la URL no debe superar los 2 048 caracteres.
Devuelve en article_url la URL canónica HTTPS exacta del artículo publicado, idéntica a su etiqueta <link rel="canonical">. Respeta la presencia o ausencia de www y la barra final. Por ejemplo, si la URL canónica es https://example.com/blog/mi-articulo, devuélvela sin www. Si es https://www.example.com/blog/mi-articulo/, conserva tanto www como la barra final. Sorank utiliza esta URL para seguir la indexación en Google Search Console. No devuelvas otra URL solo porque redirige al artículo o muestra el mismo contenido.
Una respuesta versión 2 con status: published o status: updated y una article_url válida registra inmediatamente la URL y muestra Publicado con su enlace, incluso sin intercambio de backlinks. La URL debe pertenecer al sitio del perfil. Estas respuestas completadas no esperan al verificador periódico. Solo los acuses de recibo accepted o HTTP 202 permanecen en espera de verificación. Los backlinks se verifican por separado: confirmar la publicación no prueba la presencia de los enlaces ni valida sus créditos. Si una actualización falla, se conserva la última URL verificada. Modificar el texto en el editor no lo envía automáticamente: haga clic en Enviar la actualización.

​
Nuevos intentos y procesamiento asíncrono

Utilice el encabezado Idempotency-Key para deduplicar la misma operación sobre el mismo instantáneo del artículo y devolver la respuesta memorizada. delivery_id identifica únicamente cada intento. Conserve también la correspondencia article.id para evitar creaciones duplicadas entre operaciones distintas. El encabezado X-Sorank-Article-Revision permite rechazar una versión antigua recibida después de una versión más reciente. Si el procesamiento no ha terminado, responda HTTP 202 con "sorank_webhook_version": 2, "status": "accepted" y, si se conoce, "article_url". Un 202 nunca confirma la publicación. Para permitir que Sorank verifique posteriormente esa operación asíncrona, añada únicamente tras su aplicación efectiva esta etiqueta en el HTML público del artículo:
Reemplace el valor por el del encabezado Idempotency-Key recibido. No lo añada en el momento de la recepción: la página antigua no prueba la nueva actualización. Sin esta prueba, la verificación permanece en espera y luego expira. Si su herramienta no puede publicar esta etiqueta, complete la publicación antes de devolver la respuesta 200/201.

​
Migrar una integración existente

Una respuesta 200 vacía o textual sigue siendo compatible con la entrega histórica, pero no activa las actualizaciones. Adapte su ruta, haga clic en Test y luego en Save webhook: Sorank vuelve a comprobar las capacidades del servidor al guardar. Un cambio de URL o de secreto invalida las verificaciones antiguas en curso. Para actualizar artículos ya publicados, reconstituya su correspondencia article.id en el lado del CMS; Sorank no puede deducirla.

​
Evento: article.published

Se activa cada vez que publica un artículo desde Sorank. Es el evento que su endpoint de producción debe procesar para crear la publicación en su CMS o activar su flujo de automatización. ‍

​
Evento: webhook.test

Se activa cuando hace clic en el botón Test en Sorank para verificar que su endpoint es accesible. La carga útil utiliza valores ficticios (id contiene solo ceros, featured_image se omite, images está vacío) para que su integración pueda ignorarla de forma segura o utilizarla para confirmar la conectividad sin crear una publicación real. ‍

​
Referencia de campos

  • event, article.published, article.updated o webhook.test. Utilice este campo para enrutar la carga útil.
  • delivery_id, UUID único para rastrear cada intento de entrega. Para deduplicar una operación, utilice el encabezado Idempotency-Key.
  • 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 adaptado a las URL, en minúsculas y con guiones.
  • article.meta_description, meta descripción SEO, lista para insertar en su etiqueta <meta name="description">.
  • article.focus_keyphrase, expresión clave objetivo principal utilizada para el artículo.
  • article.content, cuerpo completo del artículo en HTML, incluyendo títulos, párrafos, listas y etiquetas de imágenes en línea.
  • article.featured_image, objeto de imagen de portada con url, alt y placement. Puede estar presente en article.published y article.updated.
  • article.images, array de imágenes adicionales en el cuerpo. Cada entrada incluye url, alt y placement. Puede estar vacío.
  • article.word_count, número total de palabras del cuerpo del artículo.
  • article.keyword, idéntico a la expresión clave objetivo, conservado como campo independiente para las integraciones retrocompatibles.
  • article.language, etiqueta de idioma BCP 47 (por ejemplo en-US, fr-FR).

​
Casos de uso habituales

  • Zapier: utilice un disparador “Catch Hook” para transferir los artículos hacia miles de aplicaciones como WordPress, Notion, Airtable o Google Sheets.
  • Make: utilice un módulo Webhooks para crear automatizaciones de publicación personalizadas en varios pasos.
  • n8n: conecte un nodo Webhook a un flujo que crea la publicación en su CMS headless o su panel de administración.
  • Backend a medida: envíe los artículos directamente hacia su propia API para publicar en un sitio desarrollado a mano, un CMS headless como Sanity o Strapi, o cualquier herramienta interna.

​
Consejos

  • Haga siempre clic en Test antes de guardar para confirmar que su endpoint acepta la solicitud y devuelve una respuesta 2xx.
  • Utilice el campo event en el lado del servidor para que las llamadas webhook.test nunca creen publicaciones reales.
  • Utilice Idempotency-Key para deduplicar una operación y article.id para localizar el mismo artículo en su CMS.
  • Mantenga su Secret token privado, verifique el encabezado Authorization en cada solicitud y rote el secreto con regularidad.
  • Utilice un endpoint HTTPS para mantener los datos de los artículos seguros durante el tránsito.
  • Una vez conectado, cada artículo publicado en Sorank se enviará automáticamente hacia su URL de webhook.

​
🔄 Por qué sus 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é en línea en su sitio. Verifique cada paso para localizar el bloqueo. Estos son los puntos que debe examinar.

​
Causas del lado de su integración

  • Su clave de API del CMS es de solo lectura en lugar de lectura y escritura, este es uno de los problemas más frecuentes. Si las credenciales que su código utiliza para escribir en su CMS (Sanity, Strapi, Contentful o cualquier backend headless) solo tienen permisos de consulta / lectura, su endpoint recibirá el JSON pero fallará silenciosamente al crear la publicación. Genere una clave con acceso de escritura y actualícela en su integración.
  • Su código recibe el JSON pero nunca lo envía hacia su CMS, recibir la carga útil representa solo la mitad del trabajo. Asegúrese de que su endpoint mapea realmente los campos de Sorank y crea la publicación en su CMS o su base de datos. Registre la carga útil entrante y confirme que su llamada de publicación se ejecuta y tiene éxito.
  • El mapeo de campos es incorrecto, si su código espera nombres de campos distintos a los presentes en la carga útil, la publicación puede crearse vacía o ser rechazada. Verifique que está leyendo article.title, article.slug, article.content, etc., exactamente como se documenta arriba.
  • Su endpoint devuelve un 2xx pero lanza un error después, si acusa recibo de la solicitud antes de procesarla de forma asíncrona, un fallo posterior en su lógica de publicación no será visible para Sorank. Consulte sus propios registros de servidor para detectarlos.

​
Causas del lado de la entrega

  • Su endpoint de webhook ha dejado de responder (servidor fuera de línea), vuelva a poner su servidor en línea y verifique que la URL responde con normalidad.
  • La URL del webhook ha cambiado pero no se ha actualizado en Sorank, actualice la URL en los ajustes de integración de Sorank.
  • Ha regenerado su secreto de webhook en su lado, actualice el secreto en Sorank para que coincida con el que su servidor espera ahora en el encabezado Authorization.
  • Su endpoint devuelve un error que Sorank no puede interpretar, consulte sus registros de servidor para identificar el problema y luego corríjalo en el lado de su webhook.
  • Un cortafuegos en su servidor bloquea nuestras solicitudes, añada las direcciones IP de Sorank a la lista permitida de su cortafuegos, o autorice el User-Agent SORANK-Webhook/1.0.
  • Su endpoint tarda más de 30 segundos en responder, optimice su endpoint para que responda más rápido, o acuse recibo de la solicitud de inmediato y procésela de forma asíncrona.
Cuando Sorank no logra entregar un artículo a su endpoint, su planificador se pausa automáticamente y usted recibe un correo electrónico. En cuanto corrija el problema y reconecte su webhook en Sorank, su planificador se reanuda por sí solo. Su artículo ya está generado y almacenado de forma segura, no se pierde nada.

​
🚀 ¿No es desarrollador? Aloje su blog directamente en Sorank

El webhook le obliga a escribir y mantener código que captura el JSON y lo publica en su sitio. Si ha construido su sitio con una herramienta no-code o una herramienta de IA, como Lovable, Base44, Cursor o Claude Code, y no está en condiciones de desarrollar y alojar un endpoint que capture el webhook y publique el artículo, existe una vía mucho más sencilla. Hemos creado una solución que le permite alojar automáticamente su blog en su propio subdominio, directamente en Sorank. Sin código, sin endpoint que mantener, sin webhook que capturar. Descubra cómo funciona aquí: Aloje su blog en Sorank.

​
¿Busca una integración nativa?

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

​
¿El problema persiste tras la verificación?

Si ha verificado los puntos anteriores y la publicación sigue fallando, responda directamente al correo electrónico que ha recibido: nuestro equipo examinará lo que ocurre en su cuenta. Sus artículos permanecen generados y almacenados de forma segura en Sorank. En cuanto se restablezca la conexión, su planificador se reanuda automáticamente desde donde se había detenido.