Documentação — Notreve Hooks

🔑 Autenticação

Todas as chamadas à API requerem um Bearer token. Gere tokens em Minha Conta → Tokens de API. O valor só é exibido uma vez na criação.

Inclua o header em todas as requisições:

Authorization: Bearer SEU_TOKEN_AQUI

POST

https://api.hooks.notreve.com.br/v1 /auth/login

Login — retorna token e dados do usuário

Body (JSON)

{
  "email": "voce@empresa.com",
  "password": "sua-senha"
}

Resposta 200

{
  "status": "success",
  "data": {
    "token": "_otreve_ooks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "user": { "id": 1, "name": "João", "email": "joao@emp.com", "plan_slug": "starter" }
  }
}

📁 Projetos

Projetos agrupam endpoints de ingestão. Organize por produto, cliente ou serviço.

GET

https://api.hooks.notreve.com.br/v1/projects

Lista todos os projetos com contagem de endpoints e eventos do dia

Resposta 200

{
  "status": "success",
  "data": {
    "projects": [
      {
        "public_id": "a1b2c3d4",
        "name": "API Pagamentos",
        "description": "Integração Stripe e Pagar.me",
        "endpoints_count": 3,
        "events_today": 142,
        "created_at": "2025-01-15 10:00:00"
      }
    ],
    "plan": { "slug": "starter", "name": "Starter", "max_endpoints_total": 50, "max_events_per_day": 10000, "retention_days": 30, "retry_window_hours": 12 },
    "usage": { "events_today": 142, "events_week": 890, "events_month": 3210, "endpoints_total": 3, "projects_count": 1 }
  }
}

POST

https://api.hooks.notreve.com.br/v1/projects

Cria um novo projeto

Parâmetros

Campo	Tipo		Descrição
name	string	obrigatório	Nome do projeto
description	string	opcional	Descrição livre

Body (JSON)

{ "name": "API SMS", "description": "Notificações via Zenvia" }

GET

https://api.hooks.notreve.com.br/v1/projects/{project_id}

Detalhe do projeto com estatísticas de eventos

DEL

https://api.hooks.notreve.com.br/v1/projects/{project_id}

Exclui o projeto e todos os seus endpoints (irreversível)

🔗 Endpoints de Ingestão

Cada endpoint gera uma URL única em https://in.hooks.notreve.com.br/{endpoint_id} que recebe webhooks de qualquer origem.

GET

https://api.hooks.notreve.com.br/v1/projects/{project_id}/endpoints

Lista endpoints do projeto com contagem de eventos

Resposta 200

{
  "data": {
    "endpoints": [
      {
        "public_id": "a1b2c3d4e5f6g7h8",
        "name": "Webhook Pagamentos",
        "is_active": 1,
        "is_paused": 0,
        "target_url": "https://meuapp.com/webhooks/pagamento",
        "requests_count": 87,
        "last_request_at": "2025-05-19 14:32:00"
      }
    ]
  }
}

POST

https://api.hooks.notreve.com.br/v1/projects/{project_id}/endpoints

Cria um endpoint de ingestão. Retorna o secret HMAC — guarde-o!

Parâmetros

Campo	Tipo		Descrição
name	string	obrigatório	Nome do endpoint
target_url	string	opcional	URL de destino para reencaminhamento

Resposta 201

{
  "data": {
    "public_id": "a1b2c3d4e5f6g7h8",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "ingest_url": "https://in.hooks.notreve.com.br/a1b2c3d4e5f6g7h8"
  }
}

PUT

https://api.hooks.notreve.com.br/v1/endpoints/{endpoint_id}

Atualiza o nome ou a URL de destino do endpoint

Body (JSON)

{ "name": "Novo nome", "target_url": "https://meuapp.com/novo-webhook" }

POST

https://api.hooks.notreve.com.br/v1/endpoints/{endpoint_id}/pause

Pausa o endpoint — ingestão retorna 503 enquanto pausado

POST

https://api.hooks.notreve.com.br/v1/endpoints/{endpoint_id}/resume

Reativa um endpoint pausado

DEL

https://api.hooks.notreve.com.br/v1/endpoints/{endpoint_id}

Exclui o endpoint e todos os seus eventos (irreversível)

📥 Receber Webhooks

A URL de ingestão aceita qualquer método HTTP e Content-Type. Não requer autenticação — qualquer serviço pode enviar.

Envie webhooks para:

https://in.hooks.notreve.com.br/{endpoint_id}

ANY

https://in.hooks.notreve.com.br/{endpoint_id}

Recebe um webhook — qualquer método (POST, GET, PUT…) e Content-Type. Headers, body e metadados são armazenados.

Resposta 200 (sucesso)

{ "status": "ok", "event_id": "a1b2c3d4-..." }

Resposta 503 (endpoint pausado)

{ "status": "paused", "message": "Endpoint paused." }

Exemplo com curl

curl -X POST https://in.hooks.notreve.com.br/{endpoint_id} \
  -H "Content-Type: application/json" \
  -d '{"event":"order.created","order_id":123}'

🔒 Assinatura HMAC

O Notreve Hooks assina cada entrega com HMAC-SHA256 usando o secret do endpoint. Valide no seu servidor para rejeitar payloads não autorizados.

Header enviado em cada entrega ao target_url:

X-Webhook-Signature: sha256=HMAC_HEX

Validação em PHP:

$secret    = 'seu-secret-do-endpoint';
$payload   = file_get_contents('php://input');
$sig       = $_SERVER['HTTP_X_KORA_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);
$valid     = hash_equals($expected, $sig);

📋 Eventos

Acesse o histórico completo de webhooks recebidos: headers, body, status de entrega e tentativas.

GET

https://api.hooks.notreve.com.br/v1/endpoints/{endpoint_id}/events

Lista eventos do endpoint com status de entrega

Query params opcionais

Param	Tipo	Descrição
limit	integer	Máximo de resultados (padrão: 100)
method	string	Filtrar por método HTTP (GET, POST…)
delivery_status	string	pending \| delivered \| failed \| dlq \| no_target

GET

https://api.hooks.notreve.com.br/v1/events/{event_uuid}

Detalhe completo: headers, body, Content-Type, IP, status

Resposta 200

{
  "data": {
    "event_uuid": "a1b2c3d4-...",
    "webhook_id": "a1b2c3d4e5f6g7h8",
    "method": "POST",
    "path": "/a1b2c3d4e5f6g7h8",
    "headers": { "content-type": "application/json", "x-stripe-signature": "..." },
    "body": "{\"type\":\"charge.succeeded\",\"id\":\"ch_xxx\"}",
    "content_type": "application/json",
    "body_size": 248,
    "delivery_status": "delivered",
    "received_at": "2025-05-19 14:32:00"
  }
}

GET

https://api.hooks.notreve.com.br/v1/events/{event_uuid}/deliveries

Histórico de tentativas de entrega: status HTTP, duração, response body

Resposta 200

{
  "data": {
    "attempts": [
      {
        "attempt_number": 1,
        "attempted_at": "2025-05-19 14:32:05",
        "target_url": "https://meuapp.com/webhook",
        "response_status": 200,
        "duration_ms": 143,
        "success": true
      }
    ]
  }
}

POST

https://api.hooks.notreve.com.br/v1/events/{event_uuid}/replay

Reenvia o evento ao URL de destino configurado no endpoint

↑ Entregas manuais

Crie entregas manuais para qualquer URL externa. O Notreve Hooks gerencia entrega, retry automático e logs.

POST

https://api.hooks.notreve.com.br/v1/deliveries

Envia um webhook — entrega gerenciada com retry automático

Parâmetros

Campo	Tipo		Descrição
target_url	string	obrigatório	URL de destino
method	string	opcional	POST (padrão), PUT, PATCH, GET
payload	string	opcional	Body do request (string livre)
content_type	string	opcional	application/json (padrão)
headers	object	opcional	Headers adicionais

Body (JSON)

{
  "target_url": "https://api.parceiro.com/webhook",
  "method": "POST",
  "payload": "{\"event\":\"order.created\",\"order_id\":123}",
  "content_type": "application/json",
  "headers": { "X-Tenant-ID": "empresa-abc" }
}

GET

https://api.hooks.notreve.com.br/v1/deliveries

Lista envios com status (pending, delivered, failed, dlq)

GET

https://api.hooks.notreve.com.br/v1/deliveries/{delivery_uuid}

Detalhe e histórico de tentativas de um envio

POST

https://api.hooks.notreve.com.br/v1/deliveries/{delivery_uuid}/retry

Reenvio manual de um entrega com falha

🗝 Tokens de API

Gerencie tokens de autenticação. O valor do token só é retornado uma vez — na criação.

GET

https://api.hooks.notreve.com.br/v1/tokens

Lista todos os tokens (sem exibir o valor)

Resposta 200

{
  "data": {
    "tokens": [
      {
        "id": 1,
        "name": "ci-pipeline",
        "token_prefix": "_otreve_ooks_a1b2c",
        "created_at": "2025-05-01 09:00:00",
        "last_used_at": "2025-05-19 14:00:00"
      }
    ]
  }
}

POST

https://api.hooks.notreve.com.br/v1/tokens

Gera um novo token — valor retornado apenas uma vez

Body (JSON)

{ "name": "minha-app" }

Resposta 201

{ "data": { "token": "_otreve_ooks_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }

DEL

https://api.hooks.notreve.com.br/v1/tokens/{token_id}

Revoga o token imediatamente (irreversível)

📦 Coleção Postman

Baixe a coleção pública para testar autenticação, projetos, endpoints, ingestão pública, eventos, entregas e tokens. Rotas administrativas, criação de conta e healthchecks ficam fora da coleção pública por segurança.

Notreve Hooks API — Coleção Pública

Inclui variáveis de ambiente, exemplos de payload e organização por módulos públicos. Todas as chamadas seguem o padrão de resposta status, message, data.

📥 Baixar coleção 👀 Ver JSON

1. Importe no PostmanUse o botão Import e selecione o arquivo JSON baixado.

2. Configure variáveisPreencha {{api_url}}, {{ingest_url}}, {{token}} e IDs dos recursos.

3. Faça loginExecute Auth → Login e copie o token retornado para a variável {{token}}.

4. Teste o fluxoCrie projeto, endpoint, envie webhook no in. e acompanhe eventos/entregas.

⚡ Códigos de retorno

Código	Significado
`200`	Sucesso
`201`	Criado com sucesso
`400`	Parâmetros inválidos
`401`	Token ausente ou inválido
`403`	Sem permissão para este recurso
`404`	Recurso não encontrado
`429`	Limite de eventos atingido
`503`	Endpoint pausado

Todos os erros retornam {"status":"error","message":"Descrição do erro"}

Documentação da API

Notreve Hooks API — Coleção Pública