# Webhooks, senha criptografada, URL do Xtream e código do cliente: passo a passo no cPanel

Data: 16/10/2026

## O que mudou

1. **Senha do cliente protegida.** Ela fica **criptografada no banco** (AES-256 com a `APP_KEY`) e o sistema
   continua lendo normalmente na API, nas mensagens de WhatsApp e no CSV. Nas respostas da API, o painel e os
   tokens com a nova permissão **"Senhas dos clientes"** (`passwords`) ou `admin` recebem o campo `password`.
   Tokens criados só com leitura/escrita recebem o cliente **sem** a senha.
2. **Webhooks de saída** (Perfil → aba **Webhooks**): quando um cliente, servidor ou usuário é
   criado, alterado, renovado ou removido, o sistema faz um POST assinado (HMAC-SHA256) para a URL que você
   cadastrar. Senhas só vão se você marcar "Incluir senhas", e isso exige HTTPS.
3. **URL do Xtream** no cadastro/edição de servidor. Ela aparece na API (`xtream_url`), no webhook (no
   servidor e dentro de `server` do cliente) e como variável `{xtream_url}` nas mensagens do servidor.
4. **Código do cliente** (`code`) no cadastro/edição de cliente. Ele aparece na API (com filtro `?code=` e busca)
   e no webhook.
5. Documentação atualizada: `API_DOCUMENTATION.md` e `/api/v1/openapi.json`.

| Arquivo | Tipo |
|---|---|
| `backend/app/Casts/EncryptedString.php` | NOVO: criptografa/descriptografa a senha |
| `backend/app/Console/Commands/EncryptClientPasswords.php` | NOVO: `clients:encrypt-passwords` |
| `backend/app/Console/Commands/ProcessOutgoingWebhooks.php` | NOVO: `webhooks:process` (reenvios, via cron) |
| `backend/app/Http/Controllers/Api/OutgoingWebhookController.php` | NOVO: API dos webhooks |
| `backend/app/Models/OutgoingWebhook.php`, `OutgoingWebhookDelivery.php` | NOVOS |
| `backend/app/Observers/OutgoingWebhookObserver.php` | NOVO: dispara os eventos |
| `backend/app/Services/OutgoingWebhookService.php` | NOVO: monta, assina e envia |
| `backend/database/migrations/2026_10_16_00000{0,1,2,3}_*.php` | NOVAS: 4 migrations |
| `backend/app/Models/Client.php`, `Server.php` | alterados |
| `backend/app/Http/Controllers/Api/ClientController.php`, `ServerController.php`, `ClientImportController.php`, `ApiTokenController.php`, `OpenApiController.php` | alterados |
| `backend/app/Providers/AppServiceProvider.php` | alterado: registra o observer |
| `backend/routes/api.php` | alterado: rotas `/api/v1/outgoing-webhooks` |
| `backend/routes/console.php` | alterado: `webhooks:process` a cada minuto e limpeza diária |
| `frontend/src/components/WebhooksTab.tsx` | NOVO: tela de webhooks |
| `frontend/src/components/ApiTokensTab.tsx`, `pages/ProfilePage.tsx`, `pages/Server*.tsx`, `pages/Client*.tsx` | alterados |
| `API_DOCUMENTATION.md` | alterado |

Conteúdo desta pasta (`deploy/webhooks/`):

- `arquivos/`: versão final de todos os arquivos acima, com o mesmo caminho do projeto.
- `backup_original/`: os arquivos como eram antes (para desfazer).
- `webhooks.patch`: só as diferenças, para aplicar com `git apply`.
- `frontend_build/`: frontend já compilado, pronto para copiar para `backend/public/`.

> O código novo foi feito para **não quebrar nada** enquanto as migrations não rodarem: a senha continua em
> texto puro, a busca por código é ignorada e o cadastro de servidor funciona como antes. Por isso os arquivos
> de backend já puderam ser copiados com o sistema no ar.

---

## A) Nesta pasta (derenbox.one), onde os arquivos já foram copiados

Os arquivos de **backend** já estão no lugar (copiados em 16/10/2026). Falta o seguinte, pelo
**Terminal do cPanel**:

### 1. Backup do banco (recomendado)

Faça um backup pelo próprio painel (Admin → Banco de dados) ou pelo phpMyAdmin antes de seguir.

### 2. Rodar as 4 migrations novas

```bash
cd ~/derenbox.one/backend
php -v      # precisa ser PHP 8.3 ou mais novo
php artisan migrate --force \
  --path=database/migrations/2026_10_16_000000_change_clients_password_to_text.php \
  --path=database/migrations/2026_10_16_000001_create_outgoing_webhooks_tables.php \
  --path=database/migrations/2026_10_16_000002_add_xtream_url_to_servers_table.php \
  --path=database/migrations/2026_10_16_000003_add_code_to_clients_table.php
```

> Se `php -v` mostrar versão menor que 8.3, use o PHP do domínio, por exemplo
> `/opt/cpanel/ea-php83/root/usr/bin/php artisan ...`.

O que cada uma faz:
- `000000`: coluna `clients.password` passa de VARCHAR(255) para TEXT (cabe a senha criptografada). Não altera os valores.
- `000001`: cria as tabelas `outgoing_webhooks` e `outgoing_webhook_deliveries`.
- `000002`: cria `servers.xtream_url`.
- `000003`: cria `clients.code`.

A partir daqui, toda senha **nova ou alterada** já é gravada criptografada.

### 3. Criptografar as senhas que já existem

```bash
php artisan clients:encrypt-passwords --dry-run   # só mostra quantas seriam alteradas
php artisan clients:encrypt-passwords             # criptografa de verdade
```

Pode rodar mais de uma vez: o comando pula o que já está criptografado.

> **IMPORTANTE: guarde a `APP_KEY`** do `backend/.env`. As senhas só podem ser lidas com ela. Se a `APP_KEY`
> mudar, ou se você restaurar um backup do banco em outra instalação com outra `APP_KEY`, as senhas ficam
> ilegíveis. Para levar o banco a outro servidor, copie a mesma `APP_KEY` ou, antes, rode
> `php artisan clients:encrypt-passwords --decrypt`.

### 4. Publicar o frontend (telas novas)

O build não funciona no terminal do cPanel (o `node_modules` de lá não tem os binários Linux). O build pronto
está em `deploy/webhooks/frontend_build/`. Basta copiar:

```bash
cd ~/derenbox.one
cp backend/public/index.html deploy/webhooks/index.html.antes-webhooks   # backup
cp -r deploy/webhooks/frontend_build/assets/. backend/public/assets/ && \
cp deploy/webhooks/frontend_build/index.html backend/public/index.html
```

> Publique o frontend **depois** do passo 2: as telas novas enviam `xtream_url` e `code`, que só existem
> depois das migrations.

### 5. Cron

Não precisa de cron novo. O `schedule:run` que já roda a cada minuto passa a executar também
`webhooks:process` (reenvio do que falhou) e a limpeza diária do histórico (às 03:30). Para conferir:

```bash
php artisan schedule:list | grep webhooks
```

O envio normal acontece na hora, logo depois de cada cadastro/alteração (não depende do cron).

### 6. Testar

1. **Servidores → editar**: preencha "URL do Xtream" e salve.
2. **Clientes → editar**: preencha "Código" e salve.
3. **Perfil → Webhooks → Novo Webhook**: use uma URL de teste (ex.: https://webhook.site) e marque os eventos.
   Clique em **Testar**, depois cadastre um cliente e abra o **Histórico** para ver o conteúdo enviado.
4. **Perfil → Tokens API**: tokens que precisam ver a senha dos clientes devem ter a permissão
   **"Senhas dos clientes"**. Tokens antigos não podem ser editados: crie um novo com essa permissão.

---

## B) Em outra instalação (ex.: a pasta D:\Sistemas\GestorStream / outro cPanel)

> Em **D:\Sistemas\GestorStream** os arquivos de código já foram aplicados em 16/10/2026, junto com a
> integração EvolutionGO (`deploy/evolutiongo/`), que ainda não estava lá.

Para outra cópia do projeto:

1. Copie os arquivos de `deploy/webhooks/arquivos/` por cima do projeto (mesmos caminhos) **ou**, na raiz do
   projeto, rode `git apply deploy/webhooks/webhooks.patch` (aplique antes o `deploy/evolutiongo/evolutiongo.patch`
   se a instalação ainda não tiver o EvolutionGO).
2. Siga os passos **A.1 a A.3, A.5 e A.6**.
3. **Frontend:** o `frontend_build/` foi compilado a partir do `src/` do derenbox.one. Se o `src/` da outra
   instalação tiver alterações próprias (o D:\Sistemas\GestorStream tem, por exemplo, em `AdminSettingsPage.tsx`
   e `RegisterPage.tsx`), compile a partir dele: `cd frontend && npm run build && cp -r dist/* ../backend/public/`.

---

## Desfazer

1. Copie os arquivos de `backup_original/` de volta (os arquivos NOVOS listados acima podem ser apagados).
2. Se já criptografou as senhas: `php artisan clients:encrypt-passwords --decrypt` **antes** de reverter.
3. Reverta as migrations, uma por vez, da mais nova para a mais antiga:
   ```bash
   php artisan migrate:rollback --path=database/migrations/2026_10_16_000003_add_code_to_clients_table.php --force
   # ...e assim por diante até a 000000
   ```
4. Frontend: volte o `backend/public/index.html` do backup (`deploy/webhooks/index.html.antes-webhooks`).