Credenciais de bots e webhooks

Cada bot tem suas próprias credenciais, distintas da chave de API da organização parceira.

Modelo de segurança (recomendado)

Credencial	Objetivo	Armazenamento
Chave de API do parceiro (sk_…)	Gerenciar todos os bots, rotacionar segredos e enviar mensagens ao hub	Com hash em repouso
Token de bot (bot_….…)	Chamadas de API limitadas ao bot (webhook de entrada, futuras APIs de bot)	Com hash em repouso · exibido uma única vez
Segredo de webhook (whsec_…)	Assinar / verificar corpos de webhook com HMAC	Armazenado (necessário para assinar) · trate-o como uma senha
URL do webhook	Endpoint HTTPS do parceiro para eventos do MorisBox	URL em texto simples

Por que não usar client_id + client_secret do OAuth?

As credenciais de cliente OAuth são mais adequadas ao acesso delegado pelo usuário. Os bots se comunicam de máquina a máquina; um único token de bot de alta entropia + assinaturas HMAC nos webhooks é mais simples e robusto para esse caso de uso.

Boas práticas

1. Use somente webhooks HTTPS (localhost é permitido no desenvolvimento)
2. Inclua assinaturas HMAC-SHA256 do corpo em cada evento de saída
3. Configure opcionalmente uma allowlist de IP por bot
4. Rotacione o token / segredo sem recriar o bot
5. Nunca registre tokens completos

---

Criar um bot (os segredos são retornados uma única vez)

POST /api/v1/bots

{
  "code": "portail",
  "name": "SEED Portail",
  "runtime_mode": "local",
  "webhook_url": "https://partner.example/hooks/morisbox/portail"
}

Resposta 201

{
  "bot": {
    "code": "portail",
    "credentials": {
      "token_prefix": "bot_a1b2c3",
      "token_configured": true,
      "webhook_url": "https://partner.example/hooks/morisbox/portail",
      "webhook_secret_prefix": "whsec_ab12",
      "inbound_webhook_path": "/api/v1/bots/portail/webhook"
    }
  },
  "bot_token": "bot_a1b2c3d4e5f6.xxxxxxxx",
  "webhook_secret": "whsec_xxxxxxxx",
  "warning": "Store bot_token and webhook_secret now…"
}

Guarde bot_token e webhook_secret no seu gerenciador de segredos. Eles não podem ser consultados novamente; só podem ser regenerados por rotação.

---

Gerenciar as credenciais

Método	Caminho	Autenticação	Descrição
GET	/bots/{code}/credentials	Chave de parceiro ou token de bot	Somente prefixos
POST	/bots/{code}/token/rotate	Chave de parceiro	Novo bot_token (uma única vez)
PUT	/bots/{code}/webhook	Chave de parceiro	Definir webhook_url; opção rotate_secret
POST	/bots/{code}/webhook/secret/rotate	Chave de parceiro	Novo segredo de webhook
POST	/bots/{code}/webhook/test	Chave de parceiro	Enviar um evento de teste assinado
PATCH	/bots/{code}	Chave de parceiro	Atualizar nome, canais, allowed_ips, …

Definir o webhook

PUT /api/v1/bots/portail/webhook
Authorization: Bearer sk_…

{
  "webhook_url": "https://partner.example/hooks/morisbox/portail",
  "rotate_secret": true,
  "allowed_ips": "203.0.113.10"
}

---

Webhooks de saída (MorisBox → você)

Quando o MorisBox envia uma solicitação POST para sua webhook_url:

POST https://partner.example/hooks/morisbox/portail
Content-Type: application/json
X-Seed360-Event: bot.webhook.test
X-Seed360-Bot: portail
X-Seed360-Signature: sha256=<hex>
X-Seed360-Bot-Secret: <webhook_secret>

Corpo

{
  "event": "bot.webhook.test",
  "bot": {
    "ref": "…",
    "code": "portail",
    "partner_code": "seed"
  },
  "payload": {}
}

Verificar a assinatura (Python)

import hmac, hashlib

def verify(raw_body: bytes, header_sig: str, secret: str) -> bool:
    sig = header_sig.removeprefix("sha256=")
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

É preferível verificar o HMAC em vez de confiar apenas no cabeçalho do segredo.

---

Webhooks de entrada (você → MorisBox)

POST /api/v1/bots/{code}/webhook

Autentique-se com um dos seguintes métodos:

1. Authorization: Bearer <bot_token>
2. X-Seed360-Bot-Secret: <webhook_secret>
3. X-Seed360-Signature: sha256=<hmac of body with webhook_secret>

{
  "event": "custom.event",
  "data": { "ok": true }
}

---

Usar o token de bot

GET /api/v1/bots/portail
Authorization: Bearer bot_a1b2c3d4e5f6.xxxx

Os tokens de bot são limitados a esse bot. As chaves de API de parceiro gerenciam toda a organização.

---

Lista de verificação operacional

1. Criar o bot → guardar bot_token + webhook_secret
2. Implantar o receptor HTTPS → PUT …/webhook
3. Executar POST …/webhook/test até obter ok: true
4. Em caso de vazamento, rotacionar por token/rotate / webhook/secret/rotate