# Exemplos de Requisições para Webhooks Este documento contém exemplos de requisições para as rotas de webhook que publicam mensagens no Pub/Sub quando `MESSAGE_BROKER_DRIVER=pubsub`. ## Configuração Para que os webhooks publiquem no Pub/Sub, configure no `.env`: ```env MESSAGE_BROKER_DRIVER=pubsub GOOGLE_CLOUD_PROJECT_ID=seu-projeto-id PUBSUB_EMULATOR_HOST=pubsub-emulator:8085 # Apenas desenvolvimento # ou GOOGLE_CLOUD_KEY_FILE=/caminho/para/gcp-key.json # Produção ``` --- ## 1. Webhook Facebook/Meta Partner **Rota:** `POST /api/v1/webhook/facebook-partner` **Middleware:** `meta.webhook` ### Exemplo de Requisição (cURL) ```bash curl -X POST http://localhost:9000/api/v1/webhook/facebook-partner \ -H "Content-Type: application/json" \ -H "X-Hub-Signature-256: sha256=..." \ -d '{ "object": "whatsapp_business_account", "entry": [ { "id": "123456789", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "987654321" }, "contacts": [ { "profile": { "name": "João Silva" }, "wa_id": "5511888888888" } ], "messages": [ { "from": "5511888888888", "id": "wamid.ABC123", "timestamp": "1699123456", "text": { "body": "Olá, esta é uma mensagem de teste" }, "type": "text" } ] } } ] } ] }' ``` ### Exemplo de Payload JSON Completo ```json { "object": "whatsapp_business_account", "entry": [ { "id": "123456789", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "987654321" }, "contacts": [ { "profile": { "name": "João Silva" }, "wa_id": "5511888888888" } ], "messages": [ { "from": "5511888888888", "id": "wamid.ABC123", "timestamp": "1699123456", "text": { "body": "Olá, esta é uma mensagem de teste" }, "type": "text" } ] } } ] } ] } ``` ### Exemplo com Status de Mensagem ```json { "object": "whatsapp_business_account", "entry": [ { "id": "123456789", "changes": [ { "field": "message_status", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "987654321" }, "statuses": [ { "id": "wamid.ABC123", "status": "delivered", "timestamp": "1699123456", "recipient_id": "5511888888888" } ] } } ] } ] } ``` ### Resposta Esperada ```json { "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` **Status HTTP:** `200 OK` **O que acontece:** 1. O controller recebe o payload e adiciona `omni_request.request_id` 2. Se `MESSAGE_BROKER_ENABLED=enabled` (ou `RABBITMQ_CONSUMER=enabled`), chama `PublishWebhookMessageUseCase` 3. O use case publica no broker configurado (RabbitMQ ou Pub/Sub conforme `MESSAGE_BROKER_DRIVER`) 4. Com Pub/Sub, o tópico `OMNIBUSINESS.PROCESS_META_WH_ACCOUNT_{entry[0].id}` é criado automaticamente se não existir --- ## 2. Webhook Gupshup Partner **Rota:** `POST /api/v1/webhook/gupshup-partner` **Middleware:** `meta.webhook` ### Exemplo de Requisição (cURL) ```bash curl -X POST http://localhost:9000/api/v1/webhook/gupshup-partner \ -H "Content-Type: application/json" \ -d '{ "object": "whatsapp_business_account", "entry": [ { "id": "987654321", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "123456789" }, "contacts": [ { "profile": { "name": "Maria Santos" }, "wa_id": "5511777777777" } ], "messages": [ { "from": "5511777777777", "id": "wamid.XYZ789", "timestamp": "1699123789", "text": { "body": "Mensagem via Gupshup" }, "type": "text" } ] } } ] } ] }' ``` ### Exemplo de Payload JSON Completo ```json { "object": "whatsapp_business_account", "entry": [ { "id": "987654321", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "123456789" }, "contacts": [ { "profile": { "name": "Maria Santos" }, "wa_id": "5511777777777" } ], "messages": [ { "from": "5511777777777", "id": "wamid.XYZ789", "timestamp": "1699123789", "text": { "body": "Mensagem via Gupshup" }, "type": "text" } ] } } ] } ] } ``` ### Resposta Esperada ```json { "request_id": "660e8400-e29b-41d4-a716-446655440001" } ``` **Status HTTP:** `200 OK` **O que acontece:** 1. Mesmo fluxo do webhook Facebook/Meta 2. Publica no Pub/Sub usando `OMNIBUSINESS.PROCESS_META_WH_ACCOUNT_{entry[0].id}` --- ## 3. Verificação de Webhook (GET) Ambas as rotas suportam verificação via GET para configuração inicial: ### Facebook/Meta ```bash curl -X GET "http://localhost:9000/api/v1/webhook/facebook-partner?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=CHALLENGE_STRING" ``` ### Gupshup ```bash curl -X GET "http://localhost:9000/api/v1/webhook/gupshup-partner?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=CHALLENGE_STRING" ``` **Resposta:** Retorna o `hub.challenge` como texto plano se o token estiver correto. --- ## Estrutura do Payload Publicado no Pub/Sub Quando `MESSAGE_BROKER_ENABLED=enabled` e `MESSAGE_BROKER_DRIVER=pubsub`, o payload completo (incluindo `omni_request.request_id`) é publicado no tópico: **Tópico:** `OMNIBUSINESS.PROCESS_META_WH_ACCOUNT_{entry[0].id}` **Exemplo de payload no Pub/Sub:** ```json { "object": "whatsapp_business_account", "entry": [ { "id": "123456789", "changes": [...] } ], "omni_request": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` --- ## Testando com o Emulador Pub/Sub 1. **Inicie o emulador** (via Docker Compose): ```bash docker compose up -d pubsub-emulator ``` 2. **Configure o `.env`**: ```env MESSAGE_BROKER_DRIVER=pubsub MESSAGE_BROKER_ENABLED=enabled GCP_PROJECT_ID=local-project PUBSUB_EMULATOR_HOST=pubsub-emulator:8085 ``` 3. **Envie uma requisição** para o webhook (use os exemplos acima) 4. **Verifique a mensagem no Pub/Sub**: ```bash php artisan message-broker:pull --topic=OMNIBUSINESS.PROCESS_META_WH_ACCOUNT_123456789 ``` --- ## Pub/Sub Push É possível usar uma **subscription do tipo Push** no GCP. O Pub/Sub envia um POST para uma URL do seu backend a cada mensagem; o processamento pode rodar no **Cloud Run**, que escala automaticamente. ### Endpoint - **URL:** `POST /pubsub/push-message` (base: sua API) - **Exemplo:** `https://OMNIBUSINESS.elv.tec/pubsub/push-message` O body segue o [formato Push do GCP](https://cloud.google.com/pubsub/docs/push): `message.data` em base64 contém o payload do webhook (JSON). O controller decodifica, valida e chama o mesmo `ProcessWebhookUseCase`. ### Configurar no GCP 1. Crie uma **subscription Push** no tópico `OMNIBUSINESS.PROCESS_META_WH_ACCOUNT_{wabaId}` (um tópico por WABA). 2. Em **Endpoint URL** use a URL do endpoint acima (deve ser HTTPS e acessível pelo GCP). ### Comportamento do endpoint - **2xx:** mensagem considerada processada (ack). GCP não reenvia. - **4xx/5xx:** nack; GCP fará retry conforme a política da subscription. - Payload inválido ou erro de negócio conhecido: o endpoint retorna 200 e registra em log (evita retry infinito para mensagens inválidas). --- ## Notas Importantes - O campo `entry[0].id` é usado como identificador do WABA e para nomear a fila/tópico - O payload deve conter `object` e `entry[]` com pelo menos um item - Cada `entry` deve ter `id` e `changes[]` - Cada `change` deve ter `field` e `value` - O `request_id` é gerado automaticamente pelo controller e adicionado ao payload antes da publicação