Webhooks

Receba um HTTP POST assinado sempre que algo acontece num projeto, sem polling. Os webhooks alimentam os conectores do LLM Pulse para Zapier, Make e n8n e funcionam com qualquer backend personalizado. Disponível no plano Scale ou superior.

Tipos de evento: mention.created, competitor_mention.created, citation.created, prompt_execution.completed, sentiment.negative_detected (sentimento da marca negativo ou muito negativo), recommendation.completed, intelligence_task.completed, intelligence_task.updated (uma tarefa GEO Writer concluída foi editada manualmente ou revertida para a versão da IA).
Segurança: cada entrega inclui X-LLMPulse-Event, X-LLMPulse-Delivery (id único) e X-LLMPulse-Signature (sha256=<hex>, HMAC-SHA256 do corpo em bruto calculado com o segredo da subscrição). Verifique a assinatura para autenticar as entregas.
Entrega: uma resposta 2xx confirma a receção do evento; caso contrário, são feitas até 5 tentativas no total, incluindo a primeira, com intervalos exponenciais entre tentativas. As subscrições são desativadas automaticamente após 20 entregas falhadas consecutivas.

POST`/webhooks`

Cria uma subscrição. Idempotente: reenviar o mesmo projeto + evento + URL devolve a subscrição existente. O segredo de assinatura (whsec_...) só é devolvido por este endpoint; guarde-o para verificar as assinaturas de entrega. Requer uma chave com âmbito read_write.

Corpo (JSON):

project_idobrigatório
event_typeobrigatório, ver a lista de eventos acima
target_urlobrigatório, URL HTTPS público; são rejeitados IPs privados, localhost e nomes de anfitrião internos

Máximo de 100 subscrições ativas por conta.

GET`/webhooks`

Lista as subscrições ativas da conta. Os itens correspondem à resposta de criação sem o segredo.

Parâmetros:

project_idfiltro opcional
page
per_pagemáximo 100

DELETE`/webhooks/:id`

Elimina uma subscrição. O URL de destino deixa de receber eventos imediatamente. Requer uma chave com âmbito read_write.

Caminho:

:idid da subscrição

Devolve ERR_NOT_FOUND para subscrições que não pertencem à conta.

GET`/webhooks/sample/:event_type`

Até 3 exemplos de payloads de eventos para o tipo de evento, criados a partir dos dados reais mais recentes do projeto (ou um exemplo estático quando o projeto ainda não tem dados). Utilizado por editores de integração, como o carregador de exemplos do Zapier. Também disponível como a ferramenta MCP get_webhook_sample.

Parâmetros:

:event_typecaminho
project_idobrigatório

Exemplos de código

Download: OpenAPI Swagger Postman

Perguntar à IA: Abrir no ChatGPT Abrir no Claude Ver como Markdown

Linguagem

Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"}' \
  "https://api.llmpulse.ai/api/v1/webhooks"

const response = await fetch("https://api.llmpulse.ai/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"})
});
const data = await response.json();

import requests

response = requests.post(
    "https://api.llmpulse.ai/api/v1/webhooks",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"}
)
data = response.json()

require 'httparty'

response = HTTParty.post(
  "https://api.llmpulse.ai/api/v1/webhooks",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" },
  body: {"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"}
)
data = response.parsed_response

req, _ := http.NewRequest("POST", "https://api.llmpulse.ai/api/v1/webhooks", strings.NewReader(`{"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"}`))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.llmpulse.ai/api/v1/webhooks', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => {"project_id":"PROJECT_ID","event_type":"mention.created","target_url":"https://example.com/webhooks/llmpulse"}
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/webhooks"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"project_id\":\"PROJECT_ID\",\"event_type\":\"mention.created\",\"target_url\":\"https://example.com/webhooks/llmpulse\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/webhooks?project_id=PROJECT_ID"

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/webhooks?project_id=PROJECT_ID",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/webhooks?project_id=PROJECT_ID", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/webhooks?project_id=PROJECT_ID', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/webhooks?project_id=PROJECT_ID"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/webhooks/123"

req, _ := http.NewRequest("DELETE", "https://api.llmpulse.ai/api/v1/webhooks/123", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('DELETE', 'https://api.llmpulse.ai/api/v1/webhooks/123', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/webhooks/123"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .DELETE()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID"

const response = await fetch("https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/webhooks/sample/mention.created?project_id=PROJECT_ID"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Webhooks

POST/webhooks

GET/webhooks

DELETE/webhooks/:id

GET/webhooks/sample/:event_type

POST`/webhooks`

GET`/webhooks`

DELETE`/webhooks/:id`

GET`/webhooks/sample/:event_type`