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.

Payloads assinados com HMAC Retentativas automáticas Sem polling
Webhooks · Ao vivo
Entrega recebida http Ao vivo
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

Como funciona

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
Eventos

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.

Guia rápido

No ar em dois passos

Cadastre um endpoint e depois verifique a assinatura em cada requisição. Essa é toda a integração.

1

Cadastre um endpoint

Criar um webhook bash
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.

2

Verifique a assinatura

verify.ts typescript
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.

Payload

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.

report.completed json
{
  "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).
Confiabilidade

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.

Ver planos

Gerencie endpoints com o escopo write:webhooks; inspecione entregas com read:webhooks.

Perguntas frequentes

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?
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.
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 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 falhadas consecutivas o endpoint se autodesativa e avisamos por e-mail o dono da marca. Corrija e reative com um PATCH.
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.
A quais eventos posso me inscrever?
Quatro: report.completed, report.failed, schedule.run.completed e schedule.run.failed. Você pode rodar até 5 endpoints ativos por marca, cada um inscrito em qualquer subconjunto de eventos.
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.
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.
De qual plano eu preciso?
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.

Ainda tem dúvidas? Fale com nossa equipe

Webhooks · ao vivo

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.