funifier-mcp 0.2.26 → 0.2.27

package/datasource-funifier-docs/knowledge/modules/webhook.md

@@ -1,41 +1,388 @@
-# WebHook (WebHook)
+# `webhook`
 
-**API Endpoint:** `/v3/webhook`
+**Acesso Studio:** nenhuma tela de Studio localizada no `funifier-service` — o módulo é **API-only** (não há referência a `/studio/webhook` ou UI equivalente no código).
+**API Endpoint:** `/v3/hook` (⚠️ **não** `/v3/webhook` — ver seção 4)
+**Coleção MongoDB:** `webhook` (definida em `Entity.WEBHOOK("webhook", Webhook.class)`)
 
-## O que é
+---
 
-Notificações automáticas para endpoints externos em tempo real. Permite que a Funifier envie notificações automáticas (payloads) para sistemas externos sempre que eventos importantes ocorrem na gamificação, sem necessidade de polling.
+## 1. Visão Geral
 
-## Quando usar
+O módulo `webhook` implementa um mecanismo de **subscription/notificação push**: um sistema externo registra uma `target_url` associada a um `event`, e a Funifier faz `HTTP POST` nessa URL quando o evento ocorre — evitando que o consumidor faça polling.
 
-- Para enviar dados para sistemas de BI quando um desafio é completado
-- Para notificar CRM quando jogador atinge uma meta
-- Para integrar com ferramentas externas (Slack, Teams, etc.)
-- Para sincronizar dados em tempo real com outros sistemas
+Papel arquitetural e fatos confirmados no código:
 
-## Checklist de Configuração
+- A entidade (`Webhook.java`) tem **apenas 3 campos**: `_id`, `target_url`, `event`.
+- Existe **um único evento implementado**: `achievement_created` (constante `Webhook.EVENT_ACHIEVEMENT_CREATED`). Nenhum outro valor de `event` é disparado em qualquer ponto do código.
+- O **único ponto de disparo** em todo o `funifier-service` é `AchievementManager.fireAction(...)`, linha 827. Não há scheduler, job, fila ou outro produtor.
+- O módulo **depende do módulo Achievement** (único produtor de eventos) e é **consumido por sistemas externos**. Não há acoplamento com Trigger, mas a recomendação interna da própria plataforma (texto de prompt em `AIRest.buildZapier`) é usar **Triggers Groovy/Java com `Unirest.post`** para qualquer evento que não seja `achievement_created` — porque o módulo webhook nativo não os suporta.
+
+> O módulo resolve o caso "notifique-me quando um jogador ganhar uma conquista". Para qualquer outra necessidade de integração em tempo real, o código não oferece cobertura nativa (ver seção 7).
+
+---
+
+## 2. Arquitetura e Fluxos
+
+São dois fluxos independentes: **(A) gestão da inscrição** (REST, síncrono) e **(B) entrega do evento** (disparada pelo Achievement, síncrona).
+
+### 2.1 Pipeline A — Gestão da inscrição (REST)
+
+```
+[POST /v3/hook]        → WebhookRest.insert()      → WebhookManager.insert(hook)
+[POST /v3/hook/unsub.] → WebhookRest.unsubscribe() → WebhookManager.deleteByURL(target_url)
+[GET  /v3/hook]        → WebhookRest.findAll()     → WebhookManager.findAll()
+[GET  /v3/hook/{id}]   → WebhookRest.find()        → WebhookManager.find(id)
+[DELETE /v3/hook/{id}] → WebhookRest.delete()      → WebhookManager.delete(id)
+```
+
+Detalhe de `WebhookManager.insert(hook)`:
+
+```
+se hook != null e hook.id == null:
+    hook.id = Guid.newShortGuid()        // = new ObjectId().toString() → hex de 24 chars
+c = getJongoConnection().getCollection("webhook")
+c.save(hook)                             // Jongo save = UPSERT por _id
+```
+
+Consequência: se o `_id` for informado no corpo e já existir, `c.save()` **substitui** o documento (full replace) — POST funciona como upsert, não como create estrito (ver seção 4).
+
+### 2.2 Pipeline B — Entrega do evento (`achievement_created`)
+
+Sequência real, citando métodos:
+
+1. Uma `ActionLog` é processada → `AchievementManager.fireAction(ActionLog trigger)` (linha 117) avalia desafios/pontos/níveis e acumula `List<Achievement> result`.
+2. Etapa 5–6: `updatePlayerStatus(...)` adiciona status do jogador a `result`; conquistas de time são reavaliadas.
+3. Etapa 7 (linha 825–828): **somente se `result.size() > 0`** →
+   `manager.getWebhookManager().execute(Webhook.EVENT_ACHIEVEMENT_CREATED, result)`.
+4. `WebhookManager.execute(event, content)`:
+
+```
+hooks = getCollection("webhook").find("{event:#}", "achievement_created")
+para cada webhook em hooks:
+    tente:
+        Unirest.post(webhook.target_url)
+              .header("Content-Type", "application/json")
+              .body(JsonUtil.toJsonRemoveNullFields(content))   // content = List<Achievement>
+              .asString()
+    capture UnirestException:
+        System.out.println("WEBHOOK ERROR (id - event) : URL " + target_url)
+        e.printStackTrace()
+        // NÃO interrompe o loop; NÃO repropaga
+```
+
+Características confirmadas da entrega:
+
+- **Síncrona e sequencial** — cada hook é chamado em sequência, dentro da thread de `fireAction`. Um `target_url` lento atrasa a etapa pós-avaliação.
+- **Sem timeout configurado** no `Unirest.post` (usa o default da lib).
+- **Sem retry, sem fila, sem DLQ, sem confirmação de entrega.**
+- **Sem persistência de status** de envio.
+- Erros são **engolidos por hook** (impressos em `stdout`/`stderr`, não em logger) e não afetam o resultado da ação.
+- O corpo é `JsonUtil.toJsonRemoveNullFields(result)`: JSON indentado, campos `null` removidos. Esse helper **retorna `null`** se o Jackson lançar exceção — nesse caso o corpo do POST seria literalmente vazio/`null`.
+
+#### Fluxo de entrega — `achievement_created`
+
+```mermaid
+sequenceDiagram
+    participant Ext as Cliente (ActionLog)
+    participant AM as AchievementManager.fireAction
+    participant WM as WebhookManager.execute
+    participant DB as MongoDB (webhook)
+    participant URL as target_url externa
+
+    Ext->>AM: processa ação do jogador
+    AM->>AM: avalia desafios/pontos/níveis → List<Achievement> result
+    alt result.size() > 0
+        AM->>WM: execute("achievement_created", result)
+        WM->>DB: find({event:"achievement_created"})
+        DB-->>WM: hooks correspondentes
+        loop para cada hook (sequencial, bloqueante)
+            WM->>URL: POST target_url (body = toJsonRemoveNullFields(result))
+            alt sucesso
+                URL-->>WM: 2xx (ignorado)
+            else UnirestException
+                URL-->>WM: erro → stdout + stackTrace, continua
+            end
+        end
+    else result vazio
+        AM->>AM: nenhum webhook é disparado
+    end
+```
+
+---
+
+## 3. Estrutura dos Objetos
+
+### 3.1 `Webhook` — documento raiz
+
+Arquivo: `com/funifier/engine/webhook/Webhook.java`. Anotação de classe: `@JsonIgnoreProperties(ignoreUnknown=true)`.
+
+| Campo        | Tipo   | Padrão                          | Obrigatório   | Descrição |
+| ------------ | ------ | ------------------------------- | ------------- | --------- |
+| `_id`        | String | `ObjectId` hex se omitido       | não           | Identificador. No Java é o campo `id` mapeado via `@JsonProperty("_id")`. Se não enviado, `insert()` gera `Guid.newShortGuid()` = `new ObjectId().toString()`. |
+| `target_url` | String | —                               | de fato sim¹  | URL externa que recebe o `POST`. Não há validação de formato no código. |
+| `event`      | String | —                               | de fato sim¹  | Tipo de evento. **Único valor com efeito:** `achievement_created`. |
+
+¹ **Não há `@NotNull` nem validação explícita.** A obrigatoriedade é de fato, derivada do comportamento: um hook sem `event` jamais casa o filtro `find({event:#})` e nunca dispara; um hook com `target_url` nula faria `Unirest.post(null)` → `UnirestException` capturada e ignorada.
+
+#### Campos computados (não persistem)
+Nenhum. A entidade é plana e totalmente persistida.
+
+#### Campos removidos silenciosamente na resposta
+A serialização de saída usa `JsonUtil.toJsonRemoveNullFields` (Jackson com `Include.NON_NULL`). Qualquer um dos 3 campos que esteja `null` é **omitido** do corpo de resposta do POST.
+
+#### Campos aceitos e silenciosamente ignorados (entrada)
+Por causa de `@JsonIgnoreProperties(ignoreUnknown=true)`, **qualquer campo extra no corpo é descartado sem erro**. Tentativas comuns (baseadas em outras plataformas de webhook) que **não existem** e são ignoradas:
+
+- `headers`, `secret` / `signing_secret`, `description`, `enabled` / `active`, `method`, `retries`, `timeout`, `filter` / `criteria`, `player`, `item`.
+
+Enviar qualquer um deles retorna 201 com sucesso, mas o campo **não é persistido nem tem efeito**.
+
+#### Enum de eventos
+Não existe um `enum` — `event` é `String` livre. A única constante declarada é:
+
+| Constante | Valor | Significado operacional |
+| --------- | ----- | ----------------------- |
+| `Webhook.EVENT_ACHIEVEMENT_CREATED` | `"achievement_created"` | Disparado quando `fireAction` registra ≥1 nova conquista (progresso de desafio, level up, status do jogador). |
+
+> Qualquer outro valor de `event` pode ser salvo, mas **nunca será disparado** (não há outro `execute(...)` no código).
+
+### 3.2 Subentidades
+**Não aplicável** — entidade plana, sem objetos aninhados.
+
+### 3.3 Técnicas de jogo (`techniques`)
+**Não aplicável** — o módulo não possui códigos GT nem qualquer relação com técnicas de jogo.
+
+> **Ciclo de vida / `stateDiagram`:** não aplicável — a entidade não tem campo de status/estado. Um hook só existe ou não existe.
+
+---
+
+## 4. Endpoints
+
+Classe: `WebhookRest` — `@Path("v3/hook")`. **Esta é a única classe JAX-RS que registra o caminho** (confirmado: não existe `@Path` para `webhook` em nenhum outro lugar). O caminho documentado anteriormente como `/v3/webhook` está **incorreto**.
+
+```mermaid
+flowchart LR
+    A[POST /v3/hook] -->|insert/upsert| W[(coleção webhook)]
+    B[POST /v3/hook/unsubscribe] -->|deleteByURL| W
+    C[GET /v3/hook] -->|findAll| W
+    D[GET /v3/hook/:id] -->|find| W
+    E[DELETE /v3/hook/:id] -->|delete| W
+```
 
-- [ ] Definir URL do endpoint externo
-- [ ] Definir eventos que disparam o webhook
-- [ ] Definir formato do payload
-- [ ] Testar conectividade com endpoint
+### `POST /v3/hook` — Inscrever (subscribe)
 
-## API Endpoints
+| Aspecto               | Detalhe |
+| --------------------- | ------- |
+| Finalidade            | Registrar um webhook. |
+| Autenticação          | Credenciais via `AuthBean` (Bearer/Basic/Studio token, ou `api_key`/`X-Api-Key`). |
+| Full replace ou patch | **Upsert (full replace por `_id`)** via `c.save(hook)`. Sem `_id` → cria com id gerado. Com `_id` existente → substitui o documento inteiro. |
+| Status de retorno     | `201 CREATED` com `toJsonRemoveNullFields(hook)`. |
 
-### Listar Webhooks
-**Método:** GET
-**Endpoint:** `/v3/webhook`
+**Comportamento real:** difere do REST convencional — POST não é create estrito; é upsert. O id gerado é um `ObjectId` hex.
 
-### Criar Webhook
-**Método:** POST
-**Endpoint:** `/v3/webhook`
+**Exemplo request/response:**
+```json
+// POST /v3/hook
+{ "target_url": "https://meusistema.com/funifier-hook", "event": "achievement_created" }
+```
+```json
+// 201 CREATED
+{ "_id": "665f0b2c9a1e4d0012ab34cd", "target_url": "https://meusistema.com/funifier-hook", "event": "achievement_created" }
+```
 
-### Deletar Webhook
-**Método:** DELETE
-**Endpoint:** `/v3/webhook/:id`
+### `POST /v3/hook/unsubscribe` — Cancelar por URL
 
-## Validações e Testes
+| Aspecto               | Detalhe |
+| --------------------- | ------- |
+| Finalidade            | Remover inscrição(ões) pela `target_url`. |
+| Autenticação          | `AuthBean`. |
+| Corpo                 | `{ "target_url": "..." }` (só `target_url` é usado). |
+| Status de retorno     | `201 CREATED` (⚠️ retorna **CREATED** para uma operação de exclusão). |
+
+**Comportamento real:** `WebhookManager.deleteByURL(target_url)` executa `remove("{target_url:#}", url)` — **remove TODOS os documentos** cuja `target_url` casa, não apenas um. **Nenhuma contagem é retornada**; o corpo de resposta é o próprio hook enviado, ecoado.
+
+### `GET /v3/hook` — Listar todos
+
+| Aspecto | Detalhe |
+| ------- | ------- |
+| Finalidade | Lista todos os webhooks da organização. |
+| Autenticação | `AuthBean`. apidoc: OAuth 2.0 (client_credentials). |
+| Retorno | `200 OK`, array JSON. |
+
+### `GET /v3/hook/{id}` — Buscar por id
+
+| Aspecto | Detalhe |
+| ------- | ------- |
+| Finalidade | Retorna um webhook pelo `_id`. |
+| Autenticação | `AuthBean`. apidoc: OAuth 2.0 (client_credentials). |
+| Retorno | `200 OK`. Se não encontrado, `find` retorna `null` → corpo `null`. |
+
+### `DELETE /v3/hook/{id}` — Remover por id
+
+| Aspecto | Detalhe |
+| ------- | ------- |
+| Finalidade | Remove um webhook pelo `_id` (unsubscribe). |
+| Autenticação | `AuthBean`. apidoc: OAuth 2.0 (client_credentials). |
+| Retorno | `200 OK` com corpo `null`. Idempotente: remover id inexistente também retorna 200. |
+
+---
+
+## 5. Regras de Negócio
+
+Regras presentes no código e ausentes de qualquer schema:
+
+- **`event` é o único filtro de entrega.** Não é possível filtrar por jogador, item, desafio ou critério. Todos os hooks de `achievement_created` recebem o mesmo payload completo.
+- **POST é upsert.** Reenviar com `_id` existente substitui o documento.
+- **`unsubscribe` é "delete-all-by-url".** Uma chamada remove todos os hooks com aquela `target_url`.
+- **Campos obrigatórios são de fato, não validados.** O sistema aceita hooks malformados sem erro; eles simplesmente não funcionam.
+- **Inscrição em evento desconhecido é no-op silencioso.** O documento é salvo, mas nunca dispara.
+- **Multi-tenant por banco de dados.** `FrontController.getInstance(apiKey)` resolve a conexão Jongo da organização; a coleção `webhook` é isolada por org. Não há `organization`/`tenant` no documento — o isolamento vem do banco.
+- **Entrega só ocorre quando `result.size() > 0`** em `fireAction` — ou seja, somente quando a ação efetivamente gerou conquistas.
+
+---
+
+## 6. Comportamentos Automáticos
+
+| Comportamento | Trigger | Impacto | Persistência |
+| ------------- | ------- | ------- | ------------ |
+| Geração de `_id` | `insert()` com `id == null` | Atribui `ObjectId` hex ao hook | Persistido na coleção `webhook` |
+| Entrega `achievement_created` | `fireAction` com `result.size() > 0` | POST síncrono em cada `target_url` inscrita | **Não persiste** resultado de envio |
+| Log de erro de entrega | `UnirestException` durante o POST | `System.out.println` + `printStackTrace` | Apenas `stdout`/`stderr` |
+| Remoção em massa por URL | `POST /v3/hook/unsubscribe` | Remove N documentos com a mesma URL | Persistido (remoção) |
+
+```mermaid
+flowchart LR
+    A[ActionLog processada] --> B[fireAction avalia conquistas]
+    B --> C{result.size > 0?}
+    C -- não --> Z[fim, sem webhook]
+    C -- sim --> D["execute('achievement_created', result)"]
+    D --> E[find hooks por event]
+    E --> F{para cada hook}
+    F --> G[POST target_url síncrono]
+    G -- erro --> H[stdout + stackTrace, continua]
+    G -- ok --> I[resposta ignorada]
+```
+
+---
+
+## 7. Suportado vs NÃO Suportado
+
+### ✅ Suportado
+- Inscrever webhook (`POST /v3/hook`) com upsert por `_id`.
+- Listar (`GET /v3/hook`) e buscar por id (`GET /v3/hook/{id}`).
+- Cancelar por id (`DELETE /v3/hook/{id}`) e por URL (`POST /v3/hook/unsubscribe`).
+- Entrega push do evento `achievement_created` para todas as URLs inscritas.
+- Isolamento por organização (banco de dados por `apiKey`).
+
+### ❌ NÃO Suportado
+- **Qualquer evento além de `achievement_created`.** A documentação anterior citava "desafio completado", "jogador atinge meta", "Slack/Teams" — **nenhum desses é um evento separado**. Não existe taxonomia de eventos no código.
+- **Filtro/seleção de payload.** Sem filtro por jogador/item/critério; payload é sempre a `List<Achievement>` completa.
+- **Customização do payload** (sem template, sem mapeamento de campos).
+- **Retry, fila assíncrona, DLQ, confirmação de entrega ou histórico de envios.** Tudo síncrono e fire-and-forget.
+- **Timeout configurável** no POST de saída.
+- **Assinatura/HMAC, `secret` ou headers customizados** no POST de saída — o receptor não tem como verificar autenticidade.
+- **Headers de autenticação no POST de saída** — só `Content-Type: application/json` é enviado.
+- **Campos extras** no corpo de inscrição (`headers`, `secret`, `enabled`, etc.) — aceitos e silenciosamente descartados (`@JsonIgnoreProperties`).
+- **UI de Studio** — nenhuma tela localizada no `funifier-service`.
+- **Cobertura de testes** — nenhum arquivo de teste de webhook localizado em `src/test`.
+- **Logging estruturado de entrega** — apenas `stdout` em caso de erro.
+
+---
+
+## 8. Segurança e Permissões
+
+- **Autenticação de entrada:** todos os endpoints passam por `AuthBean`, que resolve a `apiKey` a partir de `Authorization` (Bearer/Basic/Studio/Account), `X-Api-Key` ou query `api_key`. Sem credencial válida não há `apiKey` → sem conexão de organização. A apidoc declara OAuth 2.0 (client_credentials) para GET/DELETE.
+- **Isolamento multi-tenant:** por banco de dados da organização (via `FrontController.getInstance(apiKey)`). Um cliente só enxerga/altera webhooks da própria org.
+- **SSRF (superfície real):** `target_url` é uma string arbitrária fornecida pelo cliente, e o servidor faz `Unirest.post(target_url)` diretamente. Um cliente autenticado pode apontar a URL para endereços internos/metadados da infraestrutura. **Não há allowlist nem validação de destino no código.**
+- **Ausência de autenticidade na saída:** o POST de saída não é assinado e não envia segredo/HMAC. O receptor não consegue distinguir um payload legítimo da Funifier de um forjado. Recomenda-se ao consumidor validar por outro meio (ex.: URL secreta longa).
+- **Falha de serialização silenciosa:** `toJsonRemoveNullFields` retorna `null` em exceção do Jackson — nesse caso o corpo do POST seria `null`/vazio, sem erro registrado.
+
+---
+
+## 9. Observabilidade e Troubleshooting
+
+**Diagnóstico — o módulo está funcionando?**
+- Liste as inscrições: `GET /v3/hook`.
+- Confirme que o `event` é exatamente `achievement_created` (qualquer outro valor nunca dispara).
+- Confirme que a ação realmente gera conquistas — webhooks só disparam quando `fireAction` produz `result.size() > 0`.
+
+**Sinais no log (apenas em erro):**
+```
+WEBHOOK ERROR (<id> - <event>) : URL <target_url>
+<stack trace da UnirestException>
+```
+Não há log de sucesso. Ausência de log não significa que a entrega ocorreu.
+
+**Queries úteis (Mongo, banco da organização):**
+```js
+db.webhook.find({})                              // todas as inscrições
+db.webhook.find({ event: "achievement_created" })// as que efetivamente disparam
+db.webhook.find({ target_url: "https://..." })   // localizar por destino antes de unsubscribe
+```
+
+**Comandos REST de investigação:**
+```
+GET    /v3/hook
+GET    /v3/hook/<id>
+DELETE /v3/hook/<id>
+POST   /v3/hook/unsubscribe   { "target_url": "https://..." }
+```
+
+**Erros comuns e causas:**
+- *"Cadastrei o webhook mas nada chega"* → `event` diferente de `achievement_created`; ou a ação não gerou conquista; ou `target_url` inacessível (erro foi só para stdout).
+- *"Cadastrei `secret`/`headers` e não funcionam"* → campos descartados por `@JsonIgnoreProperties`.
+- *"Processamento de ações ficou lento"* → `target_url` lenta; entrega é síncrona, sequencial e sem timeout.
+- *"Deletei por URL e sumiram vários"* → `unsubscribe` remove todos com a mesma `target_url`.
+
+---
+
+## 10. Exemplos Práticos
+
+### Exemplo mínimo funcional
+```json
+// POST /v3/hook
+{ "target_url": "https://meusistema.com/funifier", "event": "achievement_created" }
+```
+
+### Exemplo com `_id` controlado pelo cliente (upsert determinístico)
+```json
+// POST /v3/hook  → cria/atualiza sempre o mesmo documento
+{ "_id": "crm-prod-hook", "target_url": "https://crm.exemplo.com/funifier", "event": "achievement_created" }
+```
+Reenviar com o mesmo `_id` substitui a URL — útil para reconfiguração idempotente.
+
+### Cancelamento
+```json
+// POST /v3/hook/unsubscribe  → remove TODOS os hooks com esta URL
+{ "target_url": "https://crm.exemplo.com/funifier" }
+```
+```
+// ou, por id específico:
+DELETE /v3/hook/crm-prod-hook
+```
+
+### Anti-pattern — o que NÃO fazer
+```json
+// ❌ Evento inexistente: salva com 201, mas NUNCA dispara
+{ "target_url": "https://x.com/hook", "event": "challenge_completed" }
+
+// ❌ Campos que não existem: aceitos e silenciosamente ignorados
+{ "target_url": "https://x.com/hook", "event": "achievement_created",
+  "secret": "abc", "headers": { "X-Token": "..." }, "enabled": true }
+
+// ❌ target_url lenta/instável: bloqueia a etapa pós-avaliação de fireAction (entrega síncrona, sem timeout)
+```
+Para eventos diferentes de `achievement_created`, **não use este módulo** — implemente um **Trigger** (Groovy/Java) com `Unirest.post(...)`, conforme a própria orientação interna da plataforma.
+
+---
+
+## Checklist de Configuração
 
-- [ ] Webhook aparece na lista
-- [ ] Payload é enviado quando evento ocorre
-- [ ] Endpoint externo recebe dados corretamente
+- [ ] `target_url` acessível **e rápida** — a entrega é síncrona, sequencial e sem timeout configurado.
+- [ ] `event` é exatamente `achievement_created` — qualquer outro valor nunca dispara.
+- [ ] O módulo Achievement está gerando conquistas para a ação esperada (`result.size() > 0`).
+- [ ] Não confie em `secret`/`headers`/`enabled` no corpo — são silenciosamente ignorados.
+- [ ] Ciente de que `POST /v3/hook` com `_id` existente **substitui** o documento (upsert).
+- [ ] Ciente de que `unsubscribe` remove **todos** os hooks com a mesma `target_url`.
+- [ ] O consumidor valida a autenticidade por conta própria — o POST de saída não é assinado.
+- [ ] Caminho correto é `/v3/hook` (não `/v3/webhook`).