Pare de fazer polling: nós avisamos você.
Cadastre um endpoint HTTPS e o Rank Prompt envia um POST no momento em que um relatório ou uma execução agendada termina no ChatGPT, Perplexity, Google AI Mode, Claude, Gemini, Muse e Grok.
- Payloads assinados com HMAC
- Retentativas automáticas
- Sem polling
POST /webhooks/rankprompt HTTP/1.1
Host: api.yourbrand.com
X-RP-Event: report.completed
X-RP-Event-Id: evt_9b2c7e1f…
X-RP-Signature: t=1751198400,v1=5f1e9c8a2b…
Content-Type: application/json
{
"id": "evt_9b2c7e1f…",
"type": "report.completed",
"api_version": "v1",
"data": { "report_id": "f4c1…", "brand_id": "a1b2…", "status": "completed" }
}Um envio, não um polling
Você cadastra um endpoint uma vez e escolhe os momentos que importam. Assim que um relatório ou uma execução agendada termina, avisamos seus sistemas, e seguimos tentando até eles receberem.
Aponte para o Slack, para a carga do seu warehouse ou para os dashboards dos seus clientes, e eles se atualizam sozinhos assim que chegam novas respostas de IA. Você cria, rotaciona, inspeciona e reenvia em Desenvolvedores > Webhooks, ou pela API, então eles podem viver no código junto com o resto do seu stack.
- Quando Assim que o trabalho termina
- Prova Assinado, você sabe que veio da gente
- Se você cair Tentamos de novo e depois avisamos por e-mail
- Configuração O dashboard, ou uma chamada de API por endpoint
Oito momentos para reagir
Um relatório ficou pronto
Atualize o dashboard do cliente, publique a nova nota de visibilidade no Slack ou carregue as respostas no seu warehouse.
Um relatório falhou
Alerte a equipe antes que o cliente perceba, e rode de novo sem ninguém conferir na mão.
Uma execução agendada terminou
Envie os números da semana para cada interessado assim que existem, sem precisar disparar nada.
Uma execução agendada falhou
Saiba por que parou e corrija antes do próximo relatório.
A posição de uma unidade no Maps cai
local_rank.dropped chega quando uma varredura agendada do Maps encontra que a posição média de uma unidade ou sua parte no top 3 caiu além do seu alerta: abra um chamado, avise o cliente ou publique no Slack.
Um artigo entra no ar, muda ou sai
article.published, article.updated e article.unpublished, configurados no dashboard: reconstrua um site estático, avise um editor ou poste o link no Slack ou no Discord.
Chega um lead pelo seu widget
No Agency Plus, lead.created, lead.report_ready, lead.report_failed e lead.claimed chegam ao seu CRM no momento em que acontecem. Configure no dashboard.
O relatório de um prospect fica pronto ou muda de etapa
No Agency Plus, prospect.report_ready e prospect.stage_changed mantêm seu CRM em dia com o funil de prospecção. Configure no dashboard.
No ar em dois passos
Cadastre um endpoint
curl -X POST https://api.rankprompt.com/v1/brands/$BRAND_ID/webhooks \
-H "Authorization: Bearer $RANKPROMPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourbrand.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}' O secret de assinatura volta exatamente uma vez, guarde-o agora. Precisa de uma chave primeiro? Gere uma na página de Desenvolvedores.
Verifique a assinatura
import crypto from "node:crypto";
// Verify the X-RP-Signature header against the RAW request body.
export function isFromRankPrompt(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const signed = parts.t + "." + rawBody;
const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
// Constant-time compare against v1 (also accept v0 during a secret rotation).
const match = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
// Reject replays: require a recent timestamp (within 5 minutes).
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return match && fresh;
} Sempre assine sobre o corpo bruto da requisição, antes de qualquer parsing de JSON, e compare em tempo constante. Durante uma rotação de segredo, verifique também a assinatura v0.
Feito para entregar, e para verificar
Retentativas automáticas
Entregas com falha tentam de novo com backoff de 30s → 2m → 10m → 1h → 6h → 24h: até sete tentativas antes de a entrega ser descartada.
Autodesativação + alerta
Após 20 falhas consecutivas desativamos o endpoint e avisamos por e-mail o proprietário da marca. Reative com um PATCH assim que corrigir.
Entrega pelo menos uma vez
A entrega é pelo menos uma vez após o sucesso. Deduplique com X-RP-Event-Id e mantenha seus handlers idempotentes. A ordem por endpoint é preservada.
Rotação sem downtime
Rotacione o segredo de assinatura quando quiser. O segredo antigo continua assinando como v0 por 24h, então você atualiza seu verificador sem nenhum intervalo.
Log de entregas e replay
Inspecione tentativas recentes (status, código de resposta, erro) e reenvie qualquer entrega passada direto pela API.
Somente HTTPS público
Endpoints precisam ser URLs públicas https://. Alvos privados, loopback e não roteáveis são rejeitados (proteção SSRF).
Plano
Os webhooks estão incluídos em todo plano Starter ou superior, ou em um plano de API independente. É o mesmo acesso da API pública /v1 e do servidor MCP.
Gerencie endpoints com o escopo write:webhooks; inspecione entregas com read:webhooks.
Perguntas sobre webhooks
Ainda tem dúvidas? Fale com nossa equipe
Qual a diferença entre webhooks e fazer polling na API?
Você para de fazer polling do status de relatório a partir de um worker. O Rank Prompt envia um POST para seu endpoint no momento em que um relatório ou execução agendada chega a um estado terminal, então seu stack reage em segundos em vez de conforme um cron.
A quais eventos posso me inscrever?
Cinco: report.completed, report.failed, schedule.run.completed, schedule.run.failed e local_rank.dropped. Você pode rodar até 5 endpoints ativos por marca, cada um inscrito em qualquer subconjunto de eventos.
Como verifico se uma requisição realmente veio do Rank Prompt?
Toda requisição carrega um header X-RP-Signature no formato t=<timestamp>,v1=<hmac>. Recalcule um HMAC-SHA256 de "{timestamp}.{corpo bruto}" com seu segredo de assinatura e compare com v1 em tempo constante. Rejeite timestamps antigos para prevenir replays.
O que tem no payload?
Um envelope JSON pequeno: id (evt_…), type, api_version, created_at e um bloco data. O bloco data carrega os ids (report_id, brand_id, …); busque o recurso completo em /v1 quando precisar do detalhe.
O que acontece se meu endpoint estiver fora do ar?
Tentamos de novo com backoff exponencial (30s, 2m, 10m, 1h, 6h, 24h) por até sete tentativas. Após 20 entregas com falha consecutivas o endpoint se autodesativa e avisamos por e-mail o proprietário da marca. Corrija e reative com um PATCH.
Como faço a rotação do segredo de assinatura?
Envie um POST para a rota de secret-rotations do endpoint. O novo segredo é retornado uma vez e o antigo continua assinando entregas como v0 por uma sobreposição de 24 horas, então você atualiza seu verificador sem downtime.
O mesmo evento pode ser entregue duas vezes?
Sim. A entrega é pelo menos uma vez após o sucesso, então projete pensando nisso: deduplique pelo id do evento (X-RP-Event-Id) e torne seu handler idempotente. Entregas para um mesmo endpoint preservam a ordem.
De qual plano eu preciso?
Os webhooks estão incluídos em todo plano Starter ou superior, ou em um plano de API independente. Diferente da API /v1 e do servidor MCP, que qualquer plano pode usar, os webhooks começam no Starter.
Conecte o Rank Prompt ao seu stack
Escolha um plano, cadastre um endpoint e deixe os eventos de relatório e agendamento fluírem direto para seus painéis, warehouse e alertas.