Pare de fazer polling. Nós enviamos para 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 e Grok. Assinado, com retentativa e replay, para que seus painéis, warehouse e alertas reajam em segundos, não conforme um cron.
POST /webhooks/rankprompt HTTP/1.1
Host: your-app.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" }
} Assinado com HMAC-SHA256 · verificado com seu segredo
Um envio, não um polling
Cadastre um endpoint uma vez com a API pública e escolha os eventos que importam para você. Quando um relatório ou execução agendada chega a um estado terminal, enviamos um POST com um envelope JSON assinado para sua URL, tentando novamente até funcionar.
O envelope é propositalmente pequeno: carrega o tipo do evento e os ids que você precisa para fazer GET o recurso completo em /v1. Não há um botão no app, os webhooks são gerenciados totalmente pela API.
- transporte
- HTTPS POST (somente URLs públicas)
- assinatura
- X-RP-Signature · HMAC-SHA256
- eventos
- 4 tipos · relatório e agendamento
- entrega
- pelo menos uma vez · com retentativa · com replay
Quatro eventos, só estados terminais
Emitimos quando o trabalho realmente termina, concluído ou com falha, tanto para relatórios sob demanda quanto para execuções agendadas. Sem avisos de progresso barulhentos.
report.completed Um relatório manual ou agendado terminou a análise. Carrega report_id, brand_id, status e contagens de prompts.
report.failed Uma execução de relatório falhou antes de terminar. Carrega report_id, brand_id e status.
schedule.run.completed Um lote agendado terminou. Carrega scheduled_run_id, scheduled_report_id, brand_id e contagens por região.
schedule.run.failed Um lote agendado falhou. Inclui um failure_reason quando disponível.
No ar em dois passos
Cadastre um endpoint e depois verifique a assinatura em cada requisição. Essa é toda a integração.
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://your-app.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}'
# 201 Created. The signing secret is shown exactly once, so store it now:
# { "id": "whk_…", "secret": "whsec_…", "secret_version": 1, "is_active": true } 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.
Um envelope previsível
Todo evento vem no mesmo formato de envelope. O bloco de dados carrega os ids; busque o recurso completo em /v1 quando precisar de mais.
{
"id": "evt_9b2c7e1f4a8d4c0e9f2b6a1d3c5e7f90",
"type": "report.completed",
"api_version": "v1",
"created_at": "2026-06-29T12:00:00.482913+00:00",
"data": {
"report_id": "f4c1e2a0-1b2c-3d4e-5f60-7a8b9c0d1e2f",
"brand_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"scheduled_report_id": null,
"status": "completed",
"total_prompts_count": 24,
"ranked_prompts_count": 24
}
} Headers da requisição
- X-RP-Event
- O tipo do evento, por exemplo report.completed.
- X-RP-Event-Id
- Id estável do evento lógico (evt_…). Use para deduplicar.
- X-RP-Delivery-Id
- Id único para esta tentativa de entrega individual.
- X-RP-Signature
- Timestamp + HMAC-SHA256: t=…,v1=… (e v0=… durante a rotação).
Feito para entregar, e para verificar
Retentativas, autodesativação, idempotência e rotação assinada, para que um endpoint instável nunca faça você perder um evento e um segredo vazado nunca custe downtime.
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 dono 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 entitlement da API pública /v1 e do servidor MCP.
Gerencie endpoints com o escopo write:webhooks; inspecione entregas com read:webhooks.
Perguntas sobre webhooks
Tudo que os times perguntam antes de configurar um endpoint. Nos escreva se sua pergunta não está aqui.
Qual a diferença entre webhooks e fazer polling na API?
Como verifico se uma requisição realmente veio do Rank Prompt?
O que acontece se meu endpoint estiver fora do ar?
O mesmo evento pode ser entregue duas vezes?
A quais eventos posso me inscrever?
O que tem no payload?
Como faço a rotação do segredo de assinatura?
De qual plano eu preciso?
Ainda tem dúvidas? Fale com nossa equipe
Primeiro seu relatório de visibilidade em IA grátis · teste de 7 dias em qualquer plano
Conecte o Rank Prompt ao seu stack
Comece um teste grátis, cadastre um endpoint e deixe os eventos de relatório e agendamento fluírem direto para seus painéis, warehouse e alertas.