Webhooks e Postbacks

base       = "<timestamp>.<corpo bruto da requisição>"
assinatura = "sha256=" + HMAC_SHA256(segredo_do_webhook, base)

{
  "id": 789,
  "uuid": "01a1271c-a9a6-721f-938f-1bb03082bbb6",
  "userId": 1,
  "amount": "29900",
  "date": "2025-02-10T15:30:00.000Z",
  "status": "PAGO",
  "paymentMethod": "PIX",
  "customerDocument": "12345678901",
  "customerEmail": "maria.santos@example.com",
  "customerName": "Maria Silva Santos",
  "customerPhone": "11999887766",
  "pixKey": "00020126870014br.gov.bcb.pix2565pix.creditag.com.br/qr/v3/at/abc123...",
  "boletoCode": null,
  "shipping": null,
  "fee": 0,
  "saleItems": [
    {
      "id": 789,
      "saleId": 789,
      "saleUuid": "01a1271c-a9a6-721f-938f-1bb03082bbb6",
      "title": "Curso de Programação",
      "unitPrice": "29900",
      "quantity": 1,
      "tangible": false
    }
  ],
  "transactionId": 789,
  "type": "TRANSACTION"
}

{
  "amount": 29900,
  "paymentMethod": "PIX",
  "customer": {
    "name": "Maria Silva Santos",
    "email": "maria.santos@example.com"
  },
  "items": [...],
  "postbackUrl": "https://seu-servidor.com/webhook/transacao"
}

POST https://seupostbackurl.com.br/webhook/transacao
Content-Type: application/json
X-Signature: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

const crypto = require('crypto');

function validateSignature(payload, signature, secretKey) {
  // Gerar assinatura esperada usando a mesma chave secreta
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  
  // Comparar assinaturas de forma segura (timing-safe)
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Uso no endpoint
app.post('/webhook/transacao', (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = req.body;
  const secretKey = process.env.POSTBACK_SECRET_KEY;
  
  if (!validateSignature(payload, signature, secretKey)) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }
  
  // Processar notificação...
});

import hmac
import hashlib
import json
import os

def validate_signature(payload, signature, secret_key):
    """
    Valida a assinatura HMAC-SHA256 do postback.
    
    IMPORTANTE: O JSON deve ser stringificado SEM ordenação de chaves,
    exatamente como enviado pelo Nixfy Gateway.
    """
    # Gerar assinatura esperada
    payload_json = json.dumps(payload, separators=(',', ':'))
    expected_signature = hmac.new(
        secret_key.encode('utf-8'),
        payload_json.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    # Comparar assinaturas de forma segura
    return hmac.compare_digest(signature, expected_signature)

# Uso no endpoint Flask
@app.route('/webhook/transacao', methods=['POST'])
def webhook_transacao():
    signature = request.headers.get('X-Signature')
    payload = request.json
    secret_key = os.environ.get('POSTBACK_SECRET_KEY')
    
    if not validate_signature(payload, signature, secret_key):
        return jsonify({'error': 'Assinatura inválida'}), 401
    
    # Processar notificação...
    return jsonify({'success': True}), 200

{
  "id": 789,
  "uuid": "01a1271c-a9a6-721f-938f-1bb03082bbb6",
  "userId": 1,
  "amount": "29900",
  "date": "2025-02-10T15:30:00.000Z",
  "status": "PAGO",
  "paymentMethod": "PIX",
  "customerDocument": "12345678901",
  "customerEmail": "maria.santos@example.com",
  "customerName": "Maria Silva Santos",
  "customerPhone": "11999887766",
  "pixKey": "00020126870014br.gov.bcb.pix2565pix.creditag.com.br/qr/v3/at/abc123...",
  "boletoCode": null,
  "shipping": null,
  "saleItems": [
    {
      "id": 789,
      "saleId": 789,
      "saleUuid": "01a1271c-a9a6-721f-938f-1bb03082bbb6",
      "title": "Curso de Programação",
      "unitPrice": "29900",
      "quantity": 1,
      "tangible": false
    }
  ],
  "externalTransactionId": "103693454"
}

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

// Postback por Transação (com validação HMAC)
app.post('/webhook/transacao', (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = req.body;
  const secretKey = process.env.POSTBACK_SECRET_KEY;
  
  // Validar assinatura
  const hmac = crypto.createHmac('sha256', secretKey);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = hmac.digest('hex');
  
  // Comparação segura contra timing attacks
  if (!crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  )) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }
  
  // Processar notificação
  console.log('Transação atualizada:', {
    id: payload.id,
    status: payload.status,
    amount: payload.amount
  });
  
  res.status(200).json({ success: true });
});

// Webhook Permanente — assinado, com deduplicação por evento
// Use o corpo BRUTO: express.raw({ type: 'application/json' })
const processados = new Set(); // em produção, use Redis ou banco

app.post('/webhook/permanente',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const corpoBruto = req.body.toString('utf8');
    const timestamp = req.get('X-Nixfy-Timestamp');
    const recebida = req.get('X-Nixfy-Signature') || '';
    const eventId = req.get('X-Nixfy-Event-Id');
    const evento = req.get('X-Nixfy-Event-Type');

    // Recusa entregas antigas: sem isso, uma requisição capturada valeria sempre
    if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
      return res.status(401).json({ error: 'Timestamp fora da janela' });
    }

    const esperada = 'sha256=' + crypto
      .createHmac('sha256', process.env.NIXFY_WEBHOOK_SECRET)
      .update(timestamp + '.' + corpoBruto)
      .digest('hex');

    const a = Buffer.from(esperada);
    const b = Buffer.from(recebida);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).json({ error: 'Assinatura inválida' });
    }

    // Responda 2xx antes de processar — acima de 10s a entrega é abortada
    res.status(200).json({ success: true });

    // Deduplicação: sem isso, um reenvio entrega o produto duas vezes
    if (processados.has(eventId)) return;
    processados.add(eventId);

    const payload = JSON.parse(corpoBruto);
    if (evento === 'sale.paid') {
      console.log('Liberar produto da venda', payload.id);
    }
  });

app.listen(3000);

from flask import Flask, request, jsonify
import hmac
import hashlib
import json
import os
import time

app = Flask(__name__)

def validate_signature(payload, signature, secret_key):
    """
    Valida a assinatura HMAC-SHA256.
    IMPORTANTE: Não use sort_keys=True - o JSON deve ser stringificado
    exatamente como enviado pelo Nixfy Gateway.
    """
    payload_json = json.dumps(payload, separators=(',', ':'))
    expected_signature = hmac.new(
        secret_key.encode('utf-8'),
        payload_json.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# Postback por Transação (com validação HMAC)
@app.route('/webhook/transacao', methods=['POST'])
def webhook_transacao():
    signature = request.headers.get('X-Signature')
    payload = request.json
    secret_key = os.environ.get('POSTBACK_SECRET_KEY')
    
    # Validar assinatura
    if not validate_signature(payload, signature, secret_key):
        return jsonify({'error': 'Assinatura inválida'}), 401
    
    # Processar notificação
    print(f"Transação atualizada: {payload['id']} - {payload['status']}")
    
    return jsonify({'success': True}), 200

# Webhook Permanente — assinado, com deduplicação por evento
processados = set()  # em produção, use Redis ou banco

@app.route('/webhook/permanente', methods=['POST'])
def webhook_permanente():
    corpo_bruto = request.get_data(as_text=True)  # bytes brutos, não request.json
    timestamp = request.headers.get('X-Nixfy-Timestamp', '')
    recebida = request.headers.get('X-Nixfy-Signature', '')
    event_id = request.headers.get('X-Nixfy-Event-Id')
    evento = request.headers.get('X-Nixfy-Event-Type')

    # Recusa entregas antigas: sem isso, uma requisição capturada valeria sempre
    if not timestamp or abs(time.time() - float(timestamp)) > 300:
        return jsonify({'error': 'Timestamp fora da janela'}), 401

    esperada = 'sha256=' + hmac.new(
        os.environ['NIXFY_WEBHOOK_SECRET'].encode(),
        f"{timestamp}.{corpo_bruto}".encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(esperada, recebida):
        return jsonify({'error': 'Assinatura inválida'}), 401

    # Deduplicação: sem isso, um reenvio entrega o produto duas vezes
    if event_id in processados:
        return jsonify({'success': True}), 200
    processados.add(event_id)

    payload = json.loads(corpo_bruto)
    if evento == 'sale.paid':
        print(f"Liberar produto da venda {payload['id']}")

    return jsonify({'success': True}), 200

if __name__ == '__main__':
    app.run(port=3000)