Skip to content
WPP Hub

Quickstart — 10 minutos

Este guia leva voce do nada ate receber webhook real em ~10 minutos. Pre-requisito: hub do WPP Hub no ar (voce ou seu fornecedor ja deployou).

O que voce vai conseguir ao final

  • Uma app cadastrada no hub com api_key + webhook_secret
  • Um chip pareado e connected
  • Vinculo entre app e chip
  • Receber webhooks reais de mensagens recebidas
  • Enviar uma mensagem via API

Pre-requisitos

  • curl ou Postman/Insomnia
  • Sua admin key (fornecida pelo operador do hub) — geralmente comeca com ak_adm_ ou bootstrap
  • Um endpoint HTTP publico pra receber webhooks (vamos usar webhook.site como mock pra teste)
  • Telefone com WhatsApp Business OU pessoal pra parear

Passo 1 — Criar sua app

Terminal window
ADMIN_KEY="cole-sua-admin-key-aqui"
HUB="https://hub.gustavomaritan.com"


curl -X POST "$HUB/v1/apps" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha integracao",
    "webhook_url": "https://webhook.site/SEU-UUID-AQUI"
  }'

Response 201 Created:

{
  "id": "01HZTQAPP000000000000000001",
  "name": "Minha integracao",
  "api_key_prefix": "ak_live",
  "webhook_url": "https://webhook.site/...",
  "is_active": true,
  "api_key": "ak_live_4f2a8b9c...",       // ⚠️ COPIE AGORA — so aparece UMA vez
  "webhook_secret": "whsec_..."           // ⚠️ COPIE AGORA — pra validar HMAC
}

Atencao: api_key e webhook_secret so aparecem na criacao. Hub guarda apenas hash. Se perder, tem que recriar.

Salve em variaveis:

Terminal window
APP_KEY="ak_live_4f2a8b9c..."
WH_SECRET="whsec_..."

Passo 2 — Criar e parear um chip

Terminal window
curl -X POST "$HUB/v1/chips" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Chip teste" }'

Response:

{
  "id": "01HZTQCHIP00000000000000001",
  "label": "Chip teste",
  "status": "pairing",
  "qr_url": "/v1/chips/01HZTQCHIP.../qr"
}

Pegar o QR (PNG base64):

Terminal window
CHIP_ID="01HZTQCHIP..."
curl -H "Authorization: Bearer $ADMIN_KEY" \
  "$HUB/v1/chips/$CHIP_ID/qr"

Abra o resultado em algum visualizador de base64 → exibe o QR code. Escaneia no WhatsApp do celular: Aparelhos conectados → Vincular um aparelho.

Alternativa — pairing code (sem precisar de outro device)

Terminal window
curl -X POST "$HUB/v1/chips/$CHIP_ID/pair-code" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "5511999998888" }'

Response:

{ "code": "ABCD-EFGH", "phone_number": "5511999998888", "expires_at": "..." }

No celular: Aparelhos conectados → Conectar com numero de telefone → digita ABCDEFGH.

Em segundos o chip vira connected. Confirme:

Terminal window
curl -H "Authorization: Bearer $ADMIN_KEY" "$HUB/v1/chips/$CHIP_ID"
{ "id": "...", "status": "connected", "phone_number": "5511999998888", ... }

Passo 3 — Vincular app ao chip

App so envia/recebe via chips com app_chip_access. Crie o vinculo:

Terminal window
APP_ID="01HZTQAPP..."


curl -X POST "$HUB/v1/app-chip-access" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"app_id\": \"$APP_ID\",
    \"chip_id\": \"$CHIP_ID\",
    \"can_send\": true,
    \"can_receive\": true
  }"

Passo 4 — Receber primeiro webhook

No celular vinculado ao chip: mande um WhatsApp pra outra pessoa OU peca pra alguem te mandar uma mensagem.

Vai pingar no webhook.site com payload tipo:

{
  "event": "message.received",
  "timestamp": "2026-04-30T12:34:56.789Z",
  "data": {
    "message_id": "01HZTQ...",
    "chip_id": "01HZTQCHIP...",
    "from": "5511988887777@s.whatsapp.net",
    "to": "5511999998888:30@s.whatsapp.net",
    "direction": "in",
    "type": "text",
    "content": { "text": "oi, viu meu pedido?" },
    "sender": {
      "jid": "5511988887777@s.whatsapp.net",
      "name": "Maria",
      "phone_number": "5511988887777",
      "lid": "12345678901234@lid",
      "is_business": false,
      "verified_business_name": null
    },
    "chat": {
      "jid": "5511988887777@s.whatsapp.net",
      "is_group": false,
      "name": null
    }
  }
}

Headers vem com:

X-Hub-Event: message.received
X-Hub-Delivery: 01HZTQDELIVERY...
X-Hub-Signature: sha256=<hex>
X-Hub-Timestamp: 1714200000
User-Agent: WppHub/1.0

Voce deve validar a assinatura no seu endpoint — ver Webhook contract.

Passo 5 — Enviar primeira mensagem

Agora invertendo: voce manda mensagem pelo seu app (com APP_KEY).

Terminal window
curl -X POST "$HUB/v1/messages" \
  -H "Authorization: Bearer $APP_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"chip_id\": \"$CHIP_ID\",
    \"to\": \"5511988887777\",
    \"type\": \"text\",
    \"content\": { \"text\": \"resposta automatica do hub\" },
    \"idempotency_key\": \"hello-world-001\"
  }"

Response 202 Accepted:

{ "id": "01HZTQMSG...", "status": "queued" }

A mensagem entra na fila do chip (rate limit + jitter aplicados). Em segundos, o destinatario recebe.

Voce pode acompanhar o status via webhook (message.status) ou consultar:

Terminal window
MSG_ID="01HZTQMSG..."
curl -H "Authorization: Bearer $APP_KEY" "$HUB/v1/messages/$MSG_ID"

Passo 6 — Validar HMAC do webhook (codigo Node)

import crypto from 'node:crypto'
import express from 'express'


const app = express()
const SECRET = process.env.WPPHUB_WEBHOOK_SECRET // 'whsec_...'


// IMPORTANTE: precisa do body bruto pra calcular HMAC. NAO use express.json()
// antes desse middleware se voce vai validar a assinatura.
app.use('/webhook', express.raw({ type: 'application/json' }))


app.post('/webhook', (req, res) => {
  const signature = req.header('x-hub-signature') || ''
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', SECRET).update(req.body).digest('hex')


  if (
    !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return res.status(401).send('invalid signature')
  }


  const payload = JSON.parse(req.body.toString())
  console.log('event:', payload.event, 'data:', payload.data)
  res.sendStatus(200)
})


app.listen(8080)

Proximos passos