Receber e validar webhooks

​

Como o webhook é enviado

POST https://seu-servidor.com/kiwify?signature=<hmac-sha1-hex>
Content-Type: application/json

{"order_id":"…","order_status":"paid","webhook_event_type":"order_approved", …}

• O token do webhook não é enviado na requisição, nem em header, nem na query, nem no corpo. Ele é a chave usada para assinar.
• Não há outros headers de autenticação.
• Redirecionamentos não são seguidos. Responda direto na URL cadastrada.

​

Validar a assinatura

1. Leia o corpo cru (os bytes recebidos), antes de fazer o parse do JSON.
2. Calcule HMAC-SHA1(chave = token, mensagem = corpo cru) em hexadecimal.
3. Compare com o signature da query usando comparação em tempo constante.
4. Se forem diferentes, recuse a requisição (por exemplo, com 401).

​

Vetor de teste

​

Exemplos

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

const app = express();
const KIWIFY_TOKEN = process.env.KIWIFY_WEBHOOK_TOKEN;

// express.raw mantém o corpo como Buffer, sem parse
app.post('/kiwify', express.raw({ type: 'application/json' }), (req, res) => {
  const received = String(req.query.signature || '');
  const expected = crypto.createHmac('sha1', KIWIFY_TOKEN).update(req.body).digest('hex');

  const valid = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString('utf8'));
  // processe o evento…
  return res.status(200).end();
});

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)
KIWIFY_TOKEN = os.environ["KIWIFY_WEBHOOK_TOKEN"].encode()

@app.post("/kiwify")
def kiwify_webhook():
    body = request.get_data()  # bytes crus
    expected = hmac.new(KIWIFY_TOKEN, body, hashlib.sha1).hexdigest()
    if not hmac.compare_digest(expected, request.args.get("signature", "")):
        abort(401)
    event = request.get_json()
    # processe o evento…
    return "", 200

<?php
$token = getenv('KIWIFY_WEBHOOK_TOKEN');
$body = file_get_contents('php://input'); // corpo cru
$expected = hash_hmac('sha1', $body, $token);

if (!hash_equals($expected, $_GET['signature'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// processe o evento…
http_response_code(200);

​

Reenvio, duplicidade e replay

• Uma resposta 2xx confirma a entrega. Qualquer outro status, um redirecionamento ou falta de resposta em até 40 segundos contam como falha.
• Entregas que falham são reenviadas automaticamente algumas vezes, com intervalo crescente (de 1 até 10 minutos). Você também pode reenviar manualmente em Ver logs.
• O mesmo evento pode chegar mais de uma vez. Trate cada evento de forma idempotente, usando a combinação order_id + webhook_event_type.
• A assinatura não inclui data/hora nem um identificador único da entrega. Ela prova que o corpo veio de quem tem o token e não foi alterado, mas não protege contra replay: uma requisição capturada e reenviada continua com assinatura válida. A deduplicação acima é o que protege contra replay. Para confirmar o estado atual de uma venda, consulte GET /sales/{id}.

​

Trocar o token

1. Faça seu servidor aceitar a assinatura do token antigo ou do novo.
2. Troque o token na Kiwify.
3. Depois que os reenvios pendentes terminarem (espere pelo menos um dia), deixe de aceitar o token antigo.

​

Testar Webhook

​

Valores de webhook_event_type

​

Reembolso e chargeback em assinaturas

• No reembolso, subscription_canceled traz customer_access.has_access: false e access_until na data do reembolso. Veja Eventos de assinatura.
• No chargeback, customer_access não é zerado: access_until continua no fim do período pago. Remova o acesso a partir do evento chargeback, não de customer_access.
• Se a assinatura já estava cancelada, subscription_canceled não é enviado de novo.

​

Ambiente de testes

• Para testar o recebimento de webhooks, use Testar Webhook, que envia dados fictícios.
• Consultar uma venda (GET /sales/{id}) ou reembolsá-la (Reembolsar venda) só funciona com uma venda real da sua conta.