Pré-requisitos
- Token de autenticação da API (ver autenticação)
- Um servidor com endpoint HTTPS acessível publicamente
1. Preparar seu endpoint
Crie um endpoint POST no seu servidor para receber os eventos. Ele deve validar a assinatura HMAC e responder com 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;
console.log('Evento recebido:', event, data.uuid);
res.status(200).json({ received: true });
});
app.listen(3000);
2. Registrar o webhook na Plowf
Com o endpoint pronto, registre-o via API. Você pode escolher os eventos que quer receber ou omitir events para receber todos.
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",
"events": ["PAYMENT", "TRANSFER"]
}'
{
"data": {
"uuid": "e1afe0f4-9358-4a50-b0fd-55912ca86ee1",
"url": "https://seusite.com/webhooks/plowf",
"token": "token-secreto-que-voce-escolheu",
"status": "ACTIVE",
"events": ["PAYMENT", "TRANSFER"],
"created_at": "2026-01-13T00:37:47.000000Z"
}
}
Guarde o token com segurança — você vai usá-lo para validar a assinatura de todos os eventos recebidos. Se você não informar um token, a plataforma gera um automaticamente.
3. Verificar o webhook criado
Use o uuid retornado para confirmar a configuração:
curl 'https://app.plowf.com/api/v1/webhooks/e1afe0f4-9358-4a50-b0fd-55912ca86ee1' \
-H 'Authorization: Bearer seu_token_aqui'
Boas práticas
- HTTPS obrigatório: A plataforma só aceita URLs com HTTPS.
- Filtre os eventos: Especifique apenas os eventos relevantes para reduzir o volume de requisições no seu servidor.
- Idempotência: Use o
uuid do objeto recebido no evento 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.
Eventos disponíveis
| Evento | Quando é disparado |
|---|
PAYMENT | Status de uma cobrança atualizado |
TRANSFER | Status de uma transferência atualizado |
REFUND | Estorno processado |
MED | Status de um MED atualizado |
PIX_TRANSACTION | Transação PIX recebida via chave ou manual |
Referências
