Verificación de backlinks de página al publicar, paso a paso
Un webhook, una llamada HTTP, una decisión. Este manual guía a un equipo de CMS headless a través del gancho, las llamadas y los casos de fallo.
Equipo de investigación de Contentin ·
Decidir qué puede hacer la barrera
Una verificación de backlinks de página dentro de un flujo de lanzamiento es una tarea pequeña. Manténla pequeña. La parte difícil es decidir qué respuesta está permitida que cambie, porque un grafo de enlaces que se actualiza mensualmente no puede vetar una página por sí solo.
Sugerimos que la barrera emita una advertencia, registre el evento y permita que la compilación continúe. Los valores predeterminados pueden cambiar. Los bloqueos estrictos corresponden a cosas que controlas, como marcado roto o una etiqueta canonical faltante. Los datos de enlaces son una señal, y las señales varían.
Escríbelo. Hazlo antes de programarlo. Una política de una línea como "advertir al editor, etiquetar la entrada, nunca detener el despliegue" ahorra una larga discusión a las 6 pm en un día de lanzamiento. También le indica al siguiente ingeniero qué fallos fueron intencionados y cuáles fueron errores, lo cual es más importante de lo que parece. Revísala una vez al trimestre.
Seis pasos desde el clic de publicación hasta la nota almacenada
1
Elegir el desencadenante
Suscríbete al evento de publicación de tu CMS. Contentful, Sanity y Strapi pueden llamar a una URL de tu propiedad cuando se publica una entrada, y Storyblok y Payload también ofrecen webhooks o ganchos. Filtra por los tipos de contenido que contienen URLs de salida o canonical.
2
Reducir la URL a un dominio
La API toma un dominio en q, por lo que https://www.example.com/blog/post?x=1 debe convertirse primero en example.com. Decide una vez cómo tratas el www, y prueba un dominio real en la acción domain gratuita antes de construir nada.
3
Llama primero a la acción gratuita
overview no tiene coste. Si devuelve datos escasos, el dominio puede ser nuevo o simplemente desconocido para nuestro índice. Eso no es prueba de nada malo.
4
Gastar créditos solo cuando se active una regla
Cuando tu regla indique mirar más de cerca, llama a backlinks con per=100. Cuesta 2 créditos, independientemente del número de filas, así que pide una página útil de filas en lugar de diez pequeñas.
5
Escribir una nota, no el JSON en bruto
Almacena un veredicto corto en un campo propio, junto con la fecha de la verificación. Las respuestas en bruto inflan las entradas y envejecen mal, ya que el índice cambia cada mes.
6
Fallo suave
HTTP 401 significa que falta la clave o es incorrecta, así que alerta a un humano. HTTP 402 significa que se han agotado los créditos. Cualquier otro error: regístralo, omite la verificación y permite que la publicación continúe.
Dónde reside la clave y qué debe hacer un 402
Cada llamada pagada lleva tu clave, ya sea en la cadena de consulta o en un encabezado Bearer. Prefiere el encabezado. Una cadena de consulta puede terminar en los registros del servidor y en las trazas del proxy, y un encabezado generalmente permanece fuera de ellos.
Almacena la clave como un secreto en tu plataforma de alojamiento, nunca en la entrada misma. Los editores pueden leer cualquier campo que puedan abrir, pero el entorno de una función suele ser visible solo para las personas que gestionan los despliegues.
¿Dónde debería vivir la clave?
Una clave que se filtre puede gastar el saldo de tu cuenta, así que trátala como una contraseña. Manténla fuera del repositorio y fuera del CMS, y rotarla si un archivo de registro muestra alguna vez la clave en texto plano.
Etiqueta tus propios registros con el nombre del gancho. El gasto es entonces fácil de rastrear hasta una función, incluso cuando varias ganchos comparten la misma cuenta.
¿Puede una herramienta sin código hacer la llamada?
Sí, cuando la herramienta tiene un paso de solicitud HTTP simple. Muchos constructores de automatización pueden enviar un GET con una cadena de consulta y leer el JSON devuelto, por lo que la acción de resumen gratuita no necesita código.
Comienza solo con las acciones gratuitas. Un flujo que se dispara en cada guardado de borrador puede gastar créditos más rápido de lo que un editor se da cuenta, así que añade un paso pagado una vez que las llamadas gratuitas hayan corrido tranquilamente durante un tiempo.
¿Qué debería desencadenar un 402?
Un 402 significa que el saldo está vacío. No dice nada sobre la página. Omite la verificación pagada, registra el evento y envía una alerta a quien recargue la cuenta, luego permite que la publicación continúe.
Establece una alarma de saldo bien por encima de cero, para que la advertencia llegue mientras aún hay tiempo para recargar. Un bucle de reintento no ayudará aquí, porque cada llamada fallará de la misma manera hasta que alguien añada crédito. La tabla de costes tiene las cifras.
Prueba las dos llamadas desde una terminal
Ejecuta esto una vez contra un dominio que conozcas antes de que el gancho lo haga por ti. Lee el campo _credits en la segunda respuesta.
bash
# free, no key
curl -s "https://contentin.app/api.php?action=overview&q=example.com"
# 2 credits, key in a header
curl -s -H "Authorization: Bearer sk_live_..." \
"https://contentin.app/api.php?action=backlinks&q=example.com&per=100"
¿Qué dominio va en el parámetro q?
La API toma un dominio desnudo en q, por lo que una URL completa debe reducirse primero. Escribe esa reducción una vez, en una función. Luego pruébala en URLs reales.
Los enlaces relativos y los esquemas faltantes son los casos que suelen romper un gancho. Una reducción que funciona con ejemplos limpios aún puede fallar con las URLs desordenadas que un editor pega a las 5 pm.
¿Cambia www la respuesta?
Podría, y la forma honesta de averiguarlo es preguntar. Ejecuta la acción de dominio gratuita en ambas formas de un sitio que conozcas, luego compara las dos respuestas lado a lado.
Cualquiera que sea la regla que elijas, escríbela en un comentario de código para que el siguiente ingeniero no tenga que adivinar. Un comentario no cuesta nada y ahorra una larga discusión más tarde.
¿Qué pasa con las redirecciones y los subdominios?
Envía el host en el que realmente aterrizan tus lectores, no el enlace que un editor pegó hace años. Si ese enlace redirige, reduce la dirección final e ignora el salto intermedio.
Un blog en su propio subdominio es una cuestión de juicio. Decide de antemano si se verifica solo o junto con su dominio padre, y escribe esa elección junto a la regla.
Lista de verificación pre-lanzamiento para el gancho
El gancho se dispara solo en la publicación, no en cada guardado de borrador
La URL se reduce a un dominio desnudo antes de la llamada
Las acciones gratuitas se ejecutan primero y los créditos se gastan solo en una bandera
Un 401 y un 402 tienen cada uno su propia alerta y su propio mensaje
Se establece un tiempo de espera, para que una API lenta nunca bloquee a un editor
La nota almacenada lleva una fecha, para que nadie la confunda con datos en vivo
La misma entrada publicada dos veces no se factura dos veces (ver la lista de mitos)
Una línea de registro por cada verificación omitida es la pista de auditoría más barata que puedes construir. Registra el ID de la entrada, el dominio que enviaste, el código de estado y si se ejecutó un paso pagado. Usualmente eso es suficiente.
La nota almacenada se mantiene corta y fechada, como dicen los pasos anteriores. Las respuestas completas pertenecen a tus propios registros, si pertenecen a algún lugar, porque son grandes y envejecen rápidamente.
¿Qué campos pertenecen a una línea de registro?
Comienza con el ID de la entrada y la versión de publicación. Un webhook repetido aparecerá entonces como el mismo par dos veces, que es exactamente lo que quieres ver.
Añade el dominio, el nombre de la acción, el código de estado y la hora en que comenzó la llamada. Deja la clave misma fuera, ya que un registro que la contiene se convierte en un segundo lugar donde residen los secretos.
¿Cuánto tiempo debe vivir una nota almacenada?
Tanto como la entrada, a menos que una verificación más nueva la reemplace. Lo importante es que un lector pueda decir qué tan antigua es la nota, porque una nota de hace meses se lee como datos en vivo.
Ejecuta estas cuatro comprobaciones antes de que alguien confíe en el gancho.
1
Reproducir una publicación pasada
Dispara el gancho con una copia de una entrada que ya hayas publicado. Compara la nota almacenada con lo que esperabas, y confirma que la misma entrada no se facturó dos veces.
2
Prueba un dominio registrado recientemente
Usa un dominio de socio que sea nuevo para ti. Una respuesta vacía o escasa debe almacenarse como desconocida, no como un fallo, y la nota debe decirlo en palabras claras.
3
Forzar un 402 a propósito
Ejecuta el gancho con una clave en una cuenta de prueba cuyo saldo hayas vaciado. Confirma que el salto, la línea de registro y la alerta se activan todos, y que la publicación aún llega a la compilación.
4
Leer el mensaje que ve el editor
Pide a alguien fuera del equipo que lea el texto del error en voz alta. Si no pueden decir qué hacer a continuación, reescribe el mensaje antes del día del lanzamiento. El post-mortem muestra lo que costó un mensaje vago a un equipo inventado.
Lo que el gancho no puede ver
Nuestro índice se actualiza aproximadamente una vez al mes. Un enlace añadido después de la última actualización no aparecerá, y un enlace eliminado desde entonces aún puede aparecer. Para una prueba del mismo día, usa el informe de Enlaces en Google Search Console.
