Webhooks

Receba notificacoes em tempo real sobre eventos da plataforma via HTTP POST. Configure webhooks para integrar o gerador.io com seus sistemas.

Visao Geral

Webhooks permitem que voce receba notificacoes automaticas quando eventos especificos ocorrem no gerador.io. Em vez de fazer polling na API, voce registra uma URL e recebera requisicoes HTTP POST com os dados do evento.

Requisitos: Plano Pro ou Enterprise com API key ativa. Configure seus webhooks em Configuracoes da conta.

Eventos Disponiveis

Evento	Descricao	Plano
`tool_used`	Disparado quando uma ferramenta e utilizada via API	Pro
`favorite_added`	Disparado quando uma ferramenta e adicionada aos favoritos	Pro
`result_generated`	Disparado quando um resultado e gerado (ex: CPF, senha, calculo)	Enterprise

Formato da Requisicao

Cada webhook e enviado como uma requisicao POST com corpo JSON.

Headers

Content-Type: application/json
X-Gerador-Signature: sha256=abc123...
X-Gerador-Event: tool_used
X-Gerador-Delivery: evt_01H...

Payload

{
  "event": "tool_used",
  "timestamp": "2026-03-21T14:30:00Z",
  "tool_id": "gerador-de-cpf",
  "data": {
    "tool_name": "Gerador de CPF",
    "category": "documentos",
    "parameters": {
      "format": true,
      "state": "SP"
    },
    "result_count": 1
  }
}

Autenticacao

Cada requisicao webhook inclui um header X-Gerador-Signature para validar a autenticidade. O valor e um HMAC-SHA256 do corpo da requisicao usando sua webhook secret.

Verificacao em Node.js

import crypto from "crypto";

function verifySignature(payload, signature, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(payload)
      .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// No seu endpoint:
const isValid = verifySignature(
  req.body,
  req.headers["x-gerador-signature"],
  process.env.WEBHOOK_SECRET
);

Politica de Retentativas

Se o seu endpoint nao responder com um codigo HTTP 2xx em ate 10 segundos, o webhook sera reenviado automaticamente.

Tentativa	Intervalo	Delay total
1a tentativa	Imediato	0s
2a tentativa	30 segundos	30s
3a tentativa (final)	5 minutos	5min 30s

Apos 3 tentativas sem sucesso, o webhook e marcado como falho. Webhooks com falhas consecutivas podem ser desativados automaticamente apos 7 dias. Voce pode verificar o status das entregas em Configuracoes da conta.

Testando Webhooks

Use a funcao de teste no painel da conta para enviar um evento de teste ao seu endpoint. Voce tambem pode usar ferramentas como webhook.site para inspecionar as requisicoes recebidas.

Exemplo com cURL

curl -X POST https://gerador.io/api/v1/webhooks/test \
  -H "Authorization: Bearer grd_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://seu-servidor.com/webhook", "event": "tool_used"}'

← Voltar para API Docs Ver todas as integracoes →