> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Doc Sorank - Webhooks ## ¿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](/es/documentation/host-your-blog-on-sorank). Si su CMS dispone de un conector nativo, utilice el recorrido presentado en [publicar y exportar](/es/documentation/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: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` 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](https://app.sorank.com/settings/integrations/publishing). 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: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` 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: ```json theme={null} { "sorank_webhook_version": 2, "status": "published", "article_url": "https://example.com/blog/mon-article" } ``` 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 ``. 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: ```html theme={null} ``` 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 ``. * **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](/es/documentation/host-your-blog-on-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](/es/documentation/conectar-webflow), [Shopify](/es/documentation/conectar-shopify), [WordPress.org](/es/documentation/conectar-wordpress-org), [WordPress.com](/es/documentation/conectar-wordpress-com), [Wix](/es/documentation/conectar-wix) y [HubSpot](/es/documentation/usar-hubspot-con-sorank). ### ¿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.