Como integrar o IndexNow: indexação instantânea para sites, SaaS e APIs

Como integrar o IndexNow: indexação instantânea para sites, SaaS e APIs#

Durante décadas, o ciclo de vida da indexação na web operou exclusivamente no modelo pull: eu publicava uma página ou atualizava um artigo no meu site e precisava aguardar passivamente que os robôs dos motores de busca decidissem visitar o meu sitemap.xml para descobrir as novidades. Em sites com grande volume de páginas ou em domínios recentes, esse intervalo podia levar dias ou até semanas.

O protocolo IndexNow muda essa dinâmica para uma arquitetura push. Em vez de esperar pelo crawler, o meu próprio servidor avisa imediatamente aos mecanismos de busca quais páginas foram criadas, atualizadas ou removidas.

Neste guia, exploro o funcionamento do protocolo, os requisitos de validação criptográfica e compartilho implementações completas em JavaScript (Node.js), PHP, Python e automações de CI/CD para integrar no seu projeto ou SaaS.

1. O que é o IndexNow e por que ele importa?#

Lançado originalmente pela Microsoft (Bing) e pela Yandex, o IndexNow é um protocolo aberto sob licença Creative Commons. Ele resolve dois problemas centrais da infraestrutura da internet:

1. Latência de descoberta de conteúdo: O tempo entre a publicação de um artigo ou produto e a sua indexação cai de dias para segundos ou minutos. Isso é crítico para notícias, e-commerces com alterações de estoque/preços e novas páginas de produto em SaaS.
2. Desperdício de recursos de rede e CPU: Robôs tradicionais fazem varreduras repetidas em páginas inalteradas apenas para verificar se algo mudou. Com o IndexNow, os crawlers só visitam exatamente o que foi modificado.
3. Distribuição em malha (Mesh Sharing): Ao submeter uma lista de URLs para qualquer endpoint participante (como api.indexnow.org ou www.bing.com), o mecanismo que recebe a notificação compartilha automaticamente a requisição com todos os outros motores de busca parceiros cadastrados no protocolo.

Além do Bing e Yandex, o protocolo beneficia mecanismos de busca regionais (como Seznam e Naver) e motores de resposta de Inteligência Artificial que utilizam os índices dessas plataformas para sintetizar resultados em tempo real.

2. Como funciona a autenticação por chave de host#

O IndexNow dispensa autenticações complexas com OAuth ou tokens de usuário por cliente. Ele utiliza uma chave de verificação baseada no domínio (Host-Matching Key).

O processo de validação é simples:

1. Gere uma chave: Crie uma string alfanumérica aleatória em formato hexadecimal com comprimento entre 8 e 128 caracteres (o padrão recomendado é 32 caracteres em minúsculas).
2. Crie o arquivo de verificação: Salve um arquivo de texto com o nome {chave}.txt na raiz pública do seu domínio (ex: https://meudominio.com.br/2cd1cb62283949fbb51a9f02e642cb7d.txt).
3. Defina o conteúdo: O conteúdo interno desse arquivo deve ser exclusivamente a própria chave, sem espaços ou quebras de linha adicionais.
4. Envio e validação: Ao enviar uma requisição contendo as URLs e a chave, o mecanismo de busca faz uma requisição HTTP rápida ao domínio para conferir se o arquivo existe e bate com a chave declarada. Uma vez validada, o domínio é reconhecido e as URLs entram na fila prioritária de rastreamento.

Para gerar uma chave diretamente no terminal Linux:

# Gera uma chave de 32 caracteres aleatórios em hexadecimal
openssl rand -hex 16
# Exemplo de saída: 2cd1cb62283949fbb51a9f02e642cb7d

# Cria o arquivo de verificação no document root do site
echo -n "2cd1cb62283949fbb51a9f02e642cb7d" > 2cd1cb62283949fbb51a9f02e642cb7d.txt

3. Os dois formatos da API IndexNow#

O protocolo aceita dois métodos de comunicação:

Formato 1: URL Única (HTTP GET)#

Útil para sites simples, blogs pequenos ou testes manuais rápidos via navegador ou curl:

https://api.indexnow.org/indexnow?url=https://meudominio.com.br/novo-artigo.html&key=SUA_CHAVE_AQUI

Formato 2: Submissão em Lote (HTTP POST com JSON)#

O método padrão para sistemas corporativos, SaaS e pipelines de publicação. Permite enviar de 1 até 10.000 URLs em um único payload JSON:

POST /indexnow HTTP/1.1
Host: api.indexnow.org
Content-Type: application/json; charset=utf-8

{
  "host": "meudominio.com.br",
  "key": "2cd1cb62283949fbb51a9f02e642cb7d",
  "keyLocation": "https://meudominio.com.br/2cd1cb62283949fbb51a9f02e642cb7d.txt",
  "urlList": [
    "https://meudominio.com.br/pagina-1.html",
    "https://meudominio.com.br/pagina-2.html",
    "https://meudominio.com.br/produto-abc.html"
  ]
}

O parâmetro keyLocation é opcional se o arquivo {chave}.txt estiver diretamente na raiz do host, mas é altamente recomendado para evitar qualquer ambiguidade de resolução.

4. Implementação em Node.js / JavaScript#

Em ambientes Node.js modernos (APIs em Express, Fastify, Next.js ou scripts de pós-compilação de SSG), eu integro a submissão utilizando a API nativa de fetch:

// indexnow-submit.js
import fs from "node:fs";

const INDEXNOW_API = "https://api.indexnow.org/indexnow";
const HOST = "meudominio.com.br";
const KEY = "2cd1cb62283949fbb51a9f02e642cb7d";

/**
 * Envia uma lista de URLs para o endpoint do IndexNow
 * @param {string[]} urls - Lista de URLs completas para indexação
 */
export async function submitToIndexNow(urls) {
  if (!urls || urls.length === 0) {
    console.log("Nenhuma URL fornecida para submissão.");
    return { ok: false, error: "Empty URL list" };
  }

  // O protocolo aceita no máximo 10.000 URLs por requisição
  const batch = urls.slice(0, 10000);

  const payload = {
    host: HOST,
    key: KEY,
    keyLocation: `https://${HOST}/${KEY}.txt`,
    urlList: batch
  };

  try {
    const response = await fetch(INDEXNOW_API, {
      method: "POST",
      headers: {
        "Content-Type": "application/json; charset=utf-8",
        "User-Agent": "IndexNow-Client/1.0"
      },
      body: JSON.stringify(payload)
    });

    if (response.status === 200) {
      console.log(`[IndexNow] Sucesso: ${batch.length} URLs indexadas diretamente.`);
      return { ok: true, status: 200 };
    } else if (response.status === 202) {
      console.log(`[IndexNow] Aceito: ${batch.length} URLs adicionadas na fila de processamento.`);
      return { ok: true, status: 202 };
    } else {
      const errorText = await response.text();
      console.error(`[IndexNow] Erro HTTP ${response.status}:`, errorText);
      return { ok: false, status: response.status, error: errorText };
    }
  } catch (err) {
    console.error("[IndexNow] Erro de rede:", err.message);
    return { ok: false, error: err.message };
  }
}

// Exemplo de uso:
// submitToIndexNow(["https://meudominio.com.br/blog/artigo-novo.html"]);

5. Implementação em PHP#

Para sistemas em PHP puro, WordPress, Laravel ou plataformas de e-commerce, eu construo uma classe de serviço limpa utilizando cURL nativo:

<?php
// IndexNowNotifier.php

class IndexNowNotifier
{
    private string $host;
    private string $key;
    private string $endpoint;

    public function __construct(string $host, string $key, string $endpoint = 'https://api.indexnow.org/indexnow')
    {
        $this->host = $host;
        $this->key = $key;
        $this->endpoint = $endpoint;
    }

    /**
     * Envia lista de URLs para o IndexNow
     * @param array<string> $urls
     * @return array
     */
    public function notify(array $urls): array
    {
        if (empty($urls)) {
            return ['ok' => false, 'error' => 'URL list cannot be empty'];
        }

        $payload = [
            'host'        => $this->host,
            'key'         => $this->key,
            'keyLocation' => "https://{$this->host}/{$this->key}.txt",
            'urlList'     => array_values(array_slice($urls, 0, 10000))
        ];

        $jsonPayload = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

        $ch = curl_init($this->endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => $jsonPayload,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 10,
            CURLOPT_HTTPHEADER     => [
                'Content-Type: application/json; charset=utf-8',
                'Content-Length: ' . strlen($jsonPayload),
                'User-Agent: IndexNow-PHP/1.0'
            ]
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $curlError = curl_error($ch);
        curl_close($ch);

        if ($curlError !== '') {
            return ['ok' => false, 'error' => $curlError];
        }

        // 200 (OK) ou 202 (Accepted) representam submissão bem-sucedida
        if ($httpCode === 200 || $httpCode === 202) {
            return ['ok' => true, 'code' => $httpCode, 'count' => count($payload['urlList'])];
        }

        return [
            'ok'      => false,
            'code'    => $httpCode,
            'error'   => $response ?: "HTTP Error {$httpCode}"
        ];
    }
}

// Exemplo de disparo ao publicar um novo post:
// $notifier = new IndexNowNotifier('meudominio.com.br', '2cd1cb62283949fbb51a9f02e642cb7d');
// $result = $notifier->notify(['https://meudominio.com.br/blog/artigo-exemplo.html']);

6. Integração no WordPress: Rank Math e Plugin Oficial#

Nem todo projeto exige desenvolvimento sob medida ou código backend personalizado. Se você gerencia blogs, portais ou e-commerces em WordPress, existem duas formas práticas e consagradas para integrar o IndexNow sem escrever código manual:

Opção A: Rank Math SEO (Módulo Instant Indexing)#

O Rank Math foi um dos primeiros plugins de SEO a incorporar suporte nativo ao protocolo IndexNow através do seu módulo Instant Indexing:

1. Ativação do Módulo: No painel do WordPress, acesse Rank Math > Painel Geral e ative a chave Indexação Instantânea (Instant Indexing).
2. Geração da Chave de API: Ao acessar a aba de configurações do módulo, o próprio Rank Math gera uma chave de host segura automaticamente. Essa chave é servida dinamicamente pelo WordPress sem necessidade de subir arquivos manuais via FTP/SSH.
3. Seleção de Post Types: Defina quais tipos de conteúdo disparam o ping automático para o Bing e Yandex ao publicar ou atualizar (Posts, Páginas, Produtos WooCommerce ou Custom Post Types).
4. Envio Manual e em Lote (Batch): O Rank Math oferece um console direto onde é possível colar até 100 URLs de uma única vez para submissão imediata, ou acionar o botão de indexação diretamente na lista de posts do painel de administração.
5. Histórico de Submissões: O plugin mantém um log interno com a data, a URL enviada e o status HTTP retornado pelos motores de busca.

Opção B: Plugin Oficial da Microsoft (IndexNow Plugin)#

Para quem não utiliza o Rank Math e prefere uma solução isolada e ultra-leve sem suítes pesadas de SEO:

• A Microsoft disponibiliza o plugin gratuito oficial IndexNow diretamente no repositório do WordPress (wordpress.org/plugins/indexnow/).
• Uma vez instalado e ativado, ele gera a chave de validação de forma automática e silenciosa.
• O plugin monitora os hooks nativos do WordPress (save_post, transition_post_status e exclusões), enviando notificações automáticas para a API do IndexNow em segundo plano sempre que um artigo é publicado, editado ou removido, além de detectar redirecionamentos 301.

7. Implementação em Python#

Para backends em Django, FastAPI ou rotinas de scraping e automação:

# indexnow.py
import requests

def notify_indexnow(host: str, key: str, urls: list[str]) -> dict:
    if not urls:
        return {"ok": False, "error": "No URLs provided"}

    endpoint = "https://api.indexnow.org/indexnow"
    payload = {
        "host": host,
        "key": key,
        "keyLocation": f"https://{host}/{key}.txt",
        "urlList": urls[:10000]
    }

    try:
        response = requests.post(
            endpoint,
            json=payload,
            headers={"Content-Type": "application/json; charset=utf-8"},
            timeout=10
        )

        if response.status_code in (200, 202):
            return {"ok": True, "status_code": response.status_code, "count": len(urls)}
        
        return {
            "ok": False,
            "status_code": response.status_code,
            "error": response.text
        }
    except requests.RequestException as e:
        return {"ok": False, "error": str(e)}

# Exemplo:
# res = notify_indexnow("meudominio.com.br", "2cd1cb62283949fbb51a9f02e642cb7d", [
#     "https://meudominio.com.br/servicos/novo.html"
# ])
# print(res)

8. Automação em CI/CD com GitHub Actions e cURL#

Se o seu site for gerado estaticamente (Astro, Hugo, 11ty, Vite ou scripts personalizados) e hospedado em serviços como Cloudflare Pages, GitHub Pages ou Vercel, o momento perfeito para notificar os motores de busca é logo após a finalização do build no pipeline de CI/CD:

# .github/workflows/deploy-and-index.yml
name: Deploy & Notify IndexNow

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build site
        run: npm run build

      - name: Submeter novas URLs ao IndexNow
        env:
          INDEXNOW_KEY: ${{ secrets.INDEXNOW_KEY }}
        run: |
          curl -s -X POST "https://api.indexnow.org/indexnow" \
            -H "Content-Type: application/json; charset=utf-8" \
            -d '{
              "host": "meudominio.com.br",
              "key": "'"$INDEXNOW_KEY"'",
              "keyLocation": "https://meudominio.com.br/'"$INDEXNOW_KEY"'.txt",
              "urlList": [
                "https://meudominio.com.br/"
              ]
            }'

9. Tabela de Códigos de Resposta HTTP do IndexNow#

Ao integrar o protocolo, é fundamental monitorar os códigos de retorno retornados pelo endpoint:

10. Boas Práticas e Recomendações em Produção#

1. Nunca envie URLs não-canônicas ou bloqueadas: Não envie URLs que contenham tags noindex, redirecionamentos 301 intermediários ou bloqueios via robots.txt. Envie estritamente as URLs finais e limpas.
2. Evite parâmetros de tracking: Não envie URLs com ?utm_source=... ou ?fbclid=.... O IndexNow é focado na indexação de páginas primárias.
3. Agrupe alterações em lotes (Batching): Se o seu sistema publica centenas de atualizações por segundo (como um portal de notícias ou marketplace), não dispare uma requisição HTTP individual a cada INSERT no banco de dados. Armazene as URLs em uma fila (ex: Redis ou RabbitMQ) e envie um lote único a cada 10 minutos.
4. Remoção de conteúdo: Quando uma página for descontinuada e retornar 404/410, submeta a URL ao IndexNow. Isso acelera a remoção da página dos resultados de busca, diminuindo cliques perdidos de usuários.

Integrar o IndexNow é uma das etapas com melhor custo-benefício para SEO técnico moderno: a implementação leva menos de uma hora e garante que novos conteúdos fiquem disponíveis aos mecanismos de busca e sistemas de IA de forma quase instantânea.

Veja também

Desenvolvimento Atualizando o Vite no Laravel: do inotify do kernel ao manifest.json

Desenvolvimento Debugging na WhatsApp cloud API: como resolver os erros 131049 e 130472

Desenvolvimento Bun, Node.js e PM2 em produção: quando usar, quando evitar e trade-offs arquiteturais

Este post está licenciado sob CC BY-NC.