--- title: "Webhooks: documentação do CheckoutOS | Chargezen" description: "Notificações de eventos do CheckoutOS em tempo real. Da seção Referência da API da documentação do CheckoutOS da Chargezen." url: "https://chargezen.com/pt-br/docs/checkoutos/api/webhooks" lang: "pt-BR" updated: "2025-01-16" --- Canonical URL: https://chargezen.com/pt-br/docs/checkoutos/api/webhooks # Webhooks Notificações de eventos do CheckoutOS em tempo real Última atualização: 2025-01-16 Os **webhooks** permitem receber notificações em tempo real quando eventos ocorrem no CheckoutOS. Em vez de consultar a API repetidamente, os webhooks enviam dados ao seu servidor conforme os eventos acontecem. ## Eventos disponíveis #### Eventos de webhook * upsell.accepted — O cliente aceitou uma oferta de venda adicional * upsell.declined — O cliente recusou uma oferta de venda adicional * bundle.purchased — Um kit foi comprado * experiment.concluded — O teste A/B atingiu significância * order.edited — O cliente editou o pedido * order.cancelled — O cliente cancelou o pedido * subscription.created — A oferta de assinatura gerou uma conversão ## Criação de webhooks 1 #### Acessar os webhooks Acesse CheckoutOS → Settings → Webhooks. 2 #### Adicionar endpoint Clique em "Add Webhook Endpoint". 3 #### Inserir URL Insira a URL HTTPS que receberá os eventos. 4 #### Selecionar eventos Escolha quais eventos deseja receber. 5 #### Salvar Salve e anote o segredo de assinatura. Criar webhook via API ```bash curl -X POST "https://api.chargezen.com/v1/webhooks" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourserver.com/webhooks/checkoutos", "events": ["upsell.accepted", "bundle.purchased"], "enabled": true }' # Response { "id": "wh_123", "url": "https://yourserver.com/webhooks/checkoutos", "events": ["upsell.accepted", "bundle.purchased"], "signing_secret": "whsec_abc123...", "enabled": true } ``` ## Payload do webhook ### upsell.accepted Evento de oferta adicional aceita ```json { "id": "evt_123456", "type": "upsell.accepted", "created_at": "2025-01-16T14:30:00Z", "data": { "upsell_id": "upsell_abc", "upsell_name": "Premium Add-On", "order_id": "order_789", "shopify_order_id": "5678901234", "customer_id": "cust_456", "product": { "id": "prod_xyz", "title": "Premium Widget", "variant_id": "var_123", "price": 29.99 }, "discount": { "type": "percentage", "value": 15, "amount": 4.50 }, "final_price": 25.49 } } ``` ### bundle.purchased Evento de kit comprado ```json { "id": "evt_234567", "type": "bundle.purchased", "created_at": "2025-01-16T15:00:00Z", "data": { "bundle_id": "bundle_def", "bundle_name": "Skincare Starter Kit", "bundle_type": "fixed", "order_id": "order_890", "products": [ { "id": "prod_a", "title": "Cleanser", "quantity": 1 }, { "id": "prod_b", "title": "Toner", "quantity": 1 }, { "id": "prod_c", "title": "Moisturizer", "quantity": 1 } ], "original_price": 89.97, "bundle_price": 71.98, "savings": 17.99 } } ``` ### order.edited Evento de pedido editado ```json { "id": "evt_345678", "type": "order.edited", "created_at": "2025-01-16T15:30:00Z", "data": { "order_id": "order_901", "shopify_order_id": "6789012345", "edit_type": "add_items", "changes": { "items_added": [ { "product_id": "prod_new", "quantity": 1, "price": 19.99 } ], "items_removed": [], "quantity_changes": [] }, "amount_changed": 19.99, "new_total": 109.98 } } ``` ## Verificação de webhooks Todos os webhooks incluem um cabeçalho de assinatura para verificação: Verificação em Node.js ```javascript const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const expectedSignature = crypto .createHmac('sha256', secret) .update(payload, 'utf8') .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(`sha256=${expectedSignature}`) ); } // Express middleware app.post('/webhooks/checkoutos', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.headers['x-checkoutos-signature']; if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } const event = JSON.parse(req.body); // Handle event... res.status(200).send('OK'); }); ``` Verificação em Python ```python import hmac import hashlib def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode('utf-8'), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest( f'sha256={expected}', signature ) # Flask example @app.route('/webhooks/checkoutos', methods=['POST']) def handle_webhook(): signature = request.headers.get('X-CheckoutOS-Signature') if not verify_webhook(request.data, signature, WEBHOOK_SECRET): return 'Invalid signature', 401 event = request.get_json() # Handle event... return 'OK', 200 ``` Sempre verifique Sempre verifique as assinaturas dos webhooks antes do processamento. Isso impede que invasores enviem eventos falsos ao seu endpoint. ## Política de novas tentativas Entregas de webhook que falham são repetidas com intervalos que aumentam exponencialmente: Cronograma de novas tentativas ```json { "retry_policy": { "max_attempts": 5, "schedule": [ { "attempt": 1, "delay": "immediately" }, { "attempt": 2, "delay": "5 minutes" }, { "attempt": 3, "delay": "30 minutes" }, { "attempt": 4, "delay": "2 hours" }, { "attempt": 5, "delay": "24 hours" } ], "success_codes": [200, 201, 202, 204], "timeout": "30 seconds" } } ``` ## Teste de webhooks Teste o endpoint do webhook antes de colocá-lo em produção: Enviar evento de teste ```bash curl -X POST "https://api.chargezen.com/v1/webhooks/wh_123/test" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "event_type": "upsell.accepted" }' ``` ## Logs de webhooks Veja o histórico de entregas dos webhooks no painel ou pela API: Obter logs de webhooks ```bash curl -X GET "https://api.chargezen.com/v1/webhooks/wh_123/logs" \ -H "Authorization: Bearer YOUR_API_KEY" # Response { "data": [ { "id": "log_123", "event_id": "evt_456", "event_type": "upsell.accepted", "status": "delivered", "response_code": 200, "duration_ms": 245, "created_at": "2025-01-16T14:30:00Z" } ] } ``` ## Boas práticas Dicas para webhooks * **Responda rapidamente** — Retorne 200 em até 30 segundos * **Processe de forma assíncrona** — Coloque os eventos em fila para processamento em segundo plano * **Trate duplicatas** — Os eventos podem ser entregues várias vezes * **Verifique as assinaturas** — Sempre valide antes de processar * **Monitore falhas** — Configure alertas para entregas que falharem ## Tópicos relacionados [ ### Autenticação Gestão de chaves de API Saiba mais ](https://chargezen.com/pt-br/docs/checkoutos/api/authentication)[ ### Endpoints da API Referência completa dos endpoints Saiba mais ](https://chargezen.com/pt-br/docs/checkoutos/api/endpoints) Esta página foi útil? Precisa de mais ajuda? [Fale com o suporte](https://chargezen.com/pt-br/docs/checkoutos/troubleshooting/support)