Skip to main content
Para mais detalhes sobre o evento PAYMENT e a descrição completa de todos os campos do payload, consulte a referência do evento PAYMENT.

​
Visão Geral

Quando um pagamento PIX é confirmado, a Plowf envia um evento PAYMENT para seu endpoint. Esta página mostra como configurar o endpoint, registrar o webhook e reagir aos eventos.

​
Pré-requisitos

  • Token de autenticação da API (ver autenticação)
  • Um servidor com endpoint HTTPS acessível publicamente

​
1. Configurar seu endpoint de webhook

Prepare um endpoint no seu servidor para receber os eventos. Ele deve:
  • Aceitar requisições POST
  • Validar a assinatura HMAC antes de processar
  • Responder com status 2xx em até 5 segundos
const crypto = require('crypto');
const express = require('express');

const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = process.env.WEBHOOK_TOKEN;

app.post('/webhooks/plowf', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!signature) {
    return res.status(401).json({ error: 'Assinatura ausente' });
  }

  const expected = crypto
    .createHmac('sha256', WEBHOOK_TOKEN)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  const { event, data } = req.body;

  if (event === 'PAYMENT' && data.status === 'PAID') {
    // Seu pedido foi pago — atualize o banco de dados aqui
    console.log('Cobrança paga:', data.uuid, 'Ref:', data.external_ref);
  }

  res.status(200).json({ received: true });
});
Consulte a página de validação de assinatura para exemplos em Python e PHP.

​
2. Registrar o webhook na Plowf

Com seu endpoint pronto, registre-o para receber eventos PAYMENT: 
curl -X POST 'https://app.plowf.com/api/v1/webhooks' \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://seusite.com/webhooks/plowf",
    "token": "token-secreto-que-voce-escolheu"
  }'
Guarde o uuid do webhook retornado. Guarde também o token — você vai usá-lo para validar a assinatura.

​
3. Receber e processar o evento PAYMENT

Quando o pagamento for confirmado, a Plowf envia um POST para seu endpoint com este payload: 
{
  "event": "PAYMENT",
  "timestamp": "2024-01-01T10:05:00Z",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "value": 150,
    "external_ref": "PEDIDO-12345",
    "payment": {
      "pix": {
        "sender": {
          "name": "João Silva",
          "document": "12345678901"
        },
        "transaction": {
          "end_to_end": "E6070119020240101100500000000001",
          "settled_at": "2024-01-01T10:05:00Z"
        }
      }
    }
  }
}
Use o campo external_ref para identificar a qual pedido o pagamento pertence no seu sistema.

​
Status possíveis no evento PAYMENT

StatusSignificado
PENDINGAguardando pagamento
PROCESSINGPagamento em processamento
PAIDPago com sucesso
EXPIREDQR Code expirado sem pagamento
FAILEDPagamento falhou
CANCELLEDCobrança cancelada
REFUNDEDValor estornado
PARTIALLY_REFUNDEDValor estornado parcialmente

​
Boas práticas

  • Idempotência: Use o uuid da cobrança para evitar processar o mesmo evento mais de uma vez.
  • Resposta rápida: Responda 200 imediatamente e processe o evento de forma assíncrona se necessário. O timeout é de 5 segundos.
  • Nunca confie sem validar: Sempre verifique a assinatura HMAC antes de atualizar pedidos.

​
Cobranças com split

Se a cobrança tiver splits, o evento PAYMENT inclui o status de cada split no campo splits: 
{
  "event": "PAYMENT",
  "data": {
    "uuid": "770e8400-e29b-41d4-a716-446655440000",
    "status": "PAID",
    "splits": [
      {
        "uuid": "990e8400-e29b-41d4-a716-446655440002",
        "type": "PERCENTAGE",
        "value": 10,
        "status": "CREDITED",
        "recipient_account": {
          "uuid": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Empresa Parceira LTDA"
        }
      }
    ]
  }
}
O status CREDITED confirma que o split foi transferido para a conta destinatária.
Status do splitSignificado
PENDINGAguardando processamento
CREDITEDTransferido para a conta destinatária
FAILEDFalhou ao transferir

​
Referências