Question 1

Como configurar um webhook?

Accepted Answer

Em Webhooks, clique em Adicionar webhook e informe a URL do seu sistema. A Cloudfy passa a enviar os eventos do checkout (em tempo real) para essa URL, permitindo automações customizadas e provisionamento de acessos.

Question 2

Meu webhook não está disparando. O que verificar?

Accepted Answer

Se os eventos não chegam ao seu sistema, o problema costuma estar na URL ou no servidor de destino.Causas mais comunsURL incorreta ou inacessívelServidor de destino retornando erroEvento não configuradoTimeout na respostaChecklist de verificaçãoConfirme a URL cadastrada em Webhooks.Teste a URL manualmente (Postman, cURL, webhook.cool ou RequestBin).Garanta que o destino aceita requisições POST e está online.Verifique se o evento desejado está ativo.Se a URL está correta mas retorna erro 500, o problema é no servidor de destino. Persistindo, fale com o suporte.

Question 3

Como integrar com a Utmify?

Accepted Answer

A integração com a Utmify envia os seus pedidos para o rastreamento e a atribuição de conversões. O processo leva poucos minutos.1. Iniciar a integração na CloudfyNa Cloudfy, vá em Integrações, localize a Utmify e clique em Integrar. Será solicitado um API Token.2. Gerar o API Token na UtmifyNa Utmify, acesse Integrações › Webhooks › Credenciais de API e clique em Adicionar credencial. Preencha o nome que quiser, clique em Criar credencial e copie o API Token gerado.3. Colar e validar na CloudfyVolte à Cloudfy, cole o token no campo API Token e valide para confirmar que é a credencial correta.4. Selecionar os eventosMarque todas as opções de status do pedido:Pedido pendentePedido pagoPedido reembolsado ou chargebackPedido recusado5. Salvar e finalizarClique em Salvar na Cloudfy — aparecerá o aviso de que a integração foi configurada com sucesso. Por fim, volte à Utmify e clique em Finalizar.Mantenha o API Token em segredo. Em caso de dúvidas sobre a integração, fale com o suporte da Utmify ou com o nosso suporte.

Question 4

Quero integrar um site ou link, como eu faço?

Accepted Answer

Você pode direcionar o cliente para um site ou link (área de membros, grupo, formulário, etc.) usando o e-mail de pedido aprovado da Cloudfy com um botão personalizado.1. Criar o produto digitalEm Produtos › Criar produto, crie um produto digital e anexe um entregável qualquer (pode ser um arquivo simples).2. Criar o template de e-mailVá em Recuperação › Templates › Criar template. Abra outra aba e peça à sua IA de preferência para gerar um template de e-mail em HTML (aprovado), com um botão que envie para o seu link de preferência.Se quiser usar os dados do pedido no e-mail, peça à IA para incluir estes parâmetros do checkout:{{nome}}{{email}}{{telefone}}{{id}}{{total}}{{linkDoPedido}}{{downloadLink}}{{items[].nome}}3. Colar o template na CloudfyCopie o HTML que a IA gerou, volte à Cloudfy e cole em Editor do template. No topo, em Tipo de e-mail, selecione Pedido aprovado, dê um nome ao template e salve.4. Ativar o template no pedido aprovadoVá em Recuperação › Configurações, localize Pedido aprovado, clique em E-mail padrão de pedido aprovado e troque para o template que você acabou de criar.5. Conferir o domínio de e-mailPor fim, verifique se o seu e-mail está com o domínio aprovado para que possamos enviar o e-mail de pedido aprovado. Se não estiver, veja como funciona a entrega por e-mail:Entrega de infoprodutosO botão do e-mail pode apontar para qualquer URL — área de membros, grupo de WhatsApp/Telegram, formulário ou outro site.

Question 5

Documentação de Webhooks: eventos e payloads

Accepted Answer

Esta é a referência técnica dos webhooks da Cloudfy. Sempre que algo acontece em um pedido (PIX gerado, pagamento aprovado, reembolso, etc.), a Cloudfy envia uma requisição POST para a URL que você cadastrou em Webhooks, com um corpo JSON no formato abaixo. Para cadastrar a URL, veja Como configurar um webhook?.Baixar a documentação completa (PDF)Formato do eventoTodo evento chega com dois campos no nível raiz: type (o nome do evento) e payload (os dados do pedido).{   "type": "PIX_APPROVED",   "payload": { ... } }Eventos disponíveisEvento (type)Quando disparaPIX_GENERATEDPIX gerado, aguardando pagamento (status PENDING).PIX_APPROVEDPIX pago e aprovado (status APPROVED).PIX_EXPIREDPIX expirou sem pagamento.BOLETO_GENERATEDBoleto gerado, aguardando pagamento (status PENDING).BOLETO_APPROVEDBoleto pago e aprovado (status APPROVED).CREDIT_CARD_APPROVEDPagamento no cartão aprovado (status APPROVED).CREDIT_CARD_REFUSEDPagamento no cartão recusado (status REFUSED).ORDER_REFUNDEDPedido reembolsado (status REFUNDED).ORDER_CHARGED_BACKPedido sofreu chargeback (status CHARGED_BACK).CHECKOUT_ABANDONEDCheckout abandonado — o cliente preencheu os dados mas não finalizou o pagamento.Campos do payload (eventos de pedido)Os eventos de PIX, boleto e cartão compartilham a mesma estrutura de payload:CampoDescrição_idID do pedido.valueValor do pedido.items[]Lista de itens, cada um com product (name, description, img.url) e quantity.paymentMethodMétodo de pagamento: PIX, BOLETO ou CREDIT_CARD.payerNameNome de quem pagou.payerCpfCPF de quem pagou.payerEmailE-mail de quem pagou.phoneTelefone de quem pagou.installmentsNúmero de parcelas.statusStatus do pedido: PENDING, APPROVED, REFUSED, REFUNDED ou CHARGED_BACK.storeID da loja.createdAt / updatedAtDatas de criação e atualização do pedido.orderPendingUrlLink do pedido pendente.Campos específicos do PIXPresentes nos eventos PIX_GENERATED, PIX_APPROVED e PIX_EXPIRED:qrCode — código copia e cola do PIX.base64QrCode — imagem do QR Code em base64.pixDueDate — validade do PIX.Campos específicos do boletoPresentes nos eventos BOLETO_GENERATED e BOLETO_APPROVED:barCode — código de barras.digitableLine — linha digitável.externalResourceUrl — link para acessar o boleto.boletoDueDate — vencimento do boleto.Objeto shipping (entrega)Quando há endereço de entrega, o payload inclui o objeto shipping com: value, street, neighborhood, city, state, number, cep, type, complement, selectedShippingId, createdAt e updatedAt.Parâmetros de rastreamentoA Cloudfy captura automaticamente os parâmetros enviados na URL do checkout e os repassa no payload do webhook.Parâmetro na URLCampo no payloadutm_sourceutmSourceutm_campaignutmCampaignutm_mediumutmMediumutm_contentutmContentutm_termutmTermclick_id (Kwai Ads)kwaiClickIdttclid (TikTok Ads)tiktokClickIdTambém podem ser enviados xcod e subIds.Campos opcionaisOs campos abaixo são opcionais e podem não estar presentes, vir como null ou como string vazia, dependendo de como o checkout foi acessado:utmSource, utmCampaign, utmMedium, utmContent, utmTerm, xcod, subIds, kwaiClickId, tiktokClickId, shipping e orderPendingUrl.Exemplo: PIX_APPROVED{   "type": "PIX_APPROVED",   "payload": {     "_id": "673a3dca2b11ddfb67e3315c",     "value": 15,     "items": [       { "product": { "name": "Teclado gamer", "description": "lorem", "img": { "url": "image do produto" } }, "quantity": 1 }     ],     "paymentMethod": "PIX",     "payerName": "Sérgio Antonio",     "payerCpf": "087.001.240-10",     "installments": 1,     "status": "APPROVED",     "store": "66f5572e4b28b122deaa9840",     "qrCode": "pixCopiaECola",     "base64QrCode": "imagemDoQrCodeEmBase64",     "pixDueDate": "2024-11-17T19:12:34.724Z",     "phone": "(85) 98902-8127",     "payerEmail": "sergio@gmail.com",     "shipping": { "value": 14.9, "number": 123, "type": "FIXED" },     "orderPendingUrl": "https://..."   } }Evento CHECKOUT_ABANDONEDEsse evento tem um payload diferente — todos os campos são opcionais (podem vir como undefined):{   "type": "CHECKOUT_ABANDONED",   "payload": {     "storeId": "66f5572e4b28b122deaa9840",     "document": "632.444.900-93",     "email": "joao@gmail.com",     "fullName": "Joao Silva",     "phone": "(11) 1 1111-1111"   } }Sempre responda com status 200 aos webhooks e trate cada evento de forma idempotente — em casos raros o mesmo evento pode chegar mais de uma vez.

Artigos sobre integrações e webhooks

Como configurar um webhook?

Meu webhook não está disparando. O que verificar?

Como integrar com a Utmify?

Quero integrar um site ou link, como eu faço?

Documentação de Webhooks: eventos e payloads