Pix no Make

Para usar Pix no Make (antigo Integromat) com a xFlow, você monta o cenário com dois apps genéricos do Make: o HTTP, cujo módulo Make a request cria a cobrança na API Pix da xFlow, e o Webhooks, cujo módulo Custom webhook recebe o aviso de pagamento. A xFlow não tem app próprio no Make. A API é REST, com JSON, autenticação HTTP Basic e valores em centavos, e o módulo HTTP chama qualquer API assim.

Antes de começar

• Chave de API da xFlow. Gere no painel em Desenvolvedores > Chaves de API. Comece pela chave de teste (pk_test_ e sk_test_), que pode ser criada antes da aprovação do cadastro.
• Segredo do webhook. É gerado quando você cadastra a URL de webhook na xFlow. Você vai usá-lo no passo 3.

Passo 1: criar a cobrança com HTTP > Make a request

Adicione o módulo Make a request do app HTTP e preencha:

O corpo da cobrança:

{
  "amountCents": 1990,
  "customer": {
    "name": "Nome do cliente",
    "email": "cliente@exemplo.com",
    "document": "00000000000"
  },
  "external_reference": "pedido-1234"
}

Troque os valores fixos pelos campos dos módulos anteriores. O valor vai em centavos e sem aspas (R$ 19,90 é 1990), e o documento só com dígitos. No modo JSON string, a documentação do Make avisa que caracteres reservados do JSON nos valores precisam de escape manual. Se preferir montar o corpo campo a campo, use o modo Data structure.

Nas configurações avançadas, ative Return error if HTTP request fails: assim o cenário para quando a API responde 4xx ou 5xx, em vez de seguir com uma cobrança que não existe. Com Parse response em Yes, a resposta 201 vira campos mapeáveis: id, status, pix.copyPaste (copia e cola) e pix.qrCodeBase64 (imagem PNG em data-URL).

O header Idempotency-Key faz uma nova tentativa devolver a mesma cobrança, sem gerar outro Pix. Entenda em idempotência em API de pagamento.

Passo 2: receber o webhook com Custom webhook

Crie um cenário que começa com o módulo Custom webhook do app Webhooks. Nas opções avançadas, ligue:

• Get request headers, para mapear o header x-webhook-signature;
• JSON pass-through, para receber o corpo como texto, sem ser desmontado em campos.

Copie a URL do webhook e cadastre na xFlow, em Integrações > Webhooks, com o evento transaction.paid. Para o Make aprender o formato, deixe o cenário escutando e simule um pagamento no sandbox (veja abaixo).

Passo 3: validar a assinatura

Cada entrega traz x-webhook-signature: sha256=<hex>, o HMAC-SHA256 do corpo cru com o segredo do endpoint. A função sha256 do Make devolve o HMAC quando recebe uma chave. A fórmula fica assim, com o texto do corpo mapeado no primeiro argumento:

sha256=sha256(CORPO; hex; SEGREDO_DO_WEBHOOK)

O primeiro sha256= é texto fixo, o prefixo que a xFlow usa. Depois do Custom webhook, coloque um Router com duas rotas:

1. Assinatura válida. Filtro: o header x-webhook-signature é igual à fórmula acima. Em seguida, um módulo Webhook response com Status 200 e o seu processamento.
2. Assinatura inválida. Filtro: o header é diferente da fórmula. Em seguida, um Webhook response com Status 401.

Os filtros do Make comparam o texto direto, sem comparação em tempo constante. Se a sua política de segurança exigir esse tipo de comparação, valide a assinatura num servidor seu.

Passo 4: dar baixa no pedido

Na rota válida, use o módulo Parse JSON sobre o texto do corpo para ter event e data como campos. Antes de liberar qualquer coisa, confira:

• event é transaction.paid;
• data.livemode é true (eventos do sandbox chegam com false);
• o pedido de data.external_reference ainda não foi baixado.

A xFlow reenvia o evento até 3 vezes quando não recebe 2xx, então o mesmo aviso pode chegar repetido. O guia de webhook Pix mostra o formato completo do evento.

Como o Make responde à xFlow

Segundo a documentação do Make, o Webhook response tem até 180 segundos para responder. Sem esse módulo, o Make responde 200 assim que aceita o webhook na fila. Se o cenário falhar antes de responder, a resposta é 500, e a xFlow tenta de novo. Por isso o Webhook response da rota válida deve vir logo depois do filtro.

Teste no sandbox

Com o keychain da chave de teste, crie a cobrança e chame POST /api/v1/test/charges/{id}/pay num segundo Make a request, com o id da resposta. O webhook chega com livemode: false e payer: null. O passo a passo está em API Pix sandbox.

Cuidados

• Segredo do webhook no cenário. A fórmula guarda o segredo dentro do cenário. Limite quem pode editá-lo.
• Allowlist de IP. Se você restringiu as chaves por IP, inclua os endereços de saída do Make. Fora da lista, a API responde 401.
• Limite de requisições. Ao receber 429 rate_limited, espere os segundos do header retry-after.
• Plano B. Para recuperar pagamentos perdidos, chame GET /api/v1/charges?status=paid&from=...&to=....

O mesmo fluxo existe no n8n e no Zapier. O mapa completo da documentação está em Desenvolvedores.