Como usar o simulador de webhooks da Paddle no localhost

Para usar o simulador Paddle webhook com localhost, expor seu manipulador local através de um túnel HTTPS, criar um destino de notificação sandbox que aponta para a URL pública, em seguida, executar uma simulação de um evento único ou ciclo de vida contra esse destino. Paddle envia um pedido realista com um Paddle-Signature header, para que o mesmo caminho de verificação de corpo bruto possa ser executado localmente e em produção.

Por que o simulador Paddle é mais do que uma carga útil de amostra

Um dispositivo JSON copiado testa sua instrução de switch. O simulador do Paddle testa o destino da rede, cabeçalhos do provedor, assinatura secreta, status de resposta e esquema de eventos juntos. O funcionário Visão geral do simulador webhook suporta eventos e cenários únicos reutilizáveis. Eventos individuais visam um tipo de evento e podem ser personalizados após uma execução. Cenários enviam uma sequência predefinida para um ciclo de vida como a criação ou renovação de assinaturas.

A configuração do cenário pode preencher cargas úteis com entidades Paddle existentes e variar o fluxo. Cada execução produz registros de eventos de simulação onde você pode inspecionar a carga útil, solicitação de saída e resposta de endpoint. Isso torna o simulador útil para depurar transições de estado, não apenas para provar que uma rota está online.

Ligar um ponto de avaliação local à caixa de areia Paddle

1. Iniciar sua aplicação, por exemplo em http://localhost:3000.
2. Adicionar uma rota POST, como /api/webhooks/paddle.
3. Executar npx portpreview 3000 e copiar o endereço HTTPS.
4. Na caixa de areia Paddle, crie um destino de notificação usando https://your-subdomain.portpreview.dev/api/webhooks/paddle.
5. Revelar e copiar o segredo do ponto final desse destino para PADDLE_WEBHOOK_SECRET. Não é a sua chave API.
6. Abrir ferramentas de desenvolvimento → Simulações, escolha um único evento ou cenário, selecione o destino, configure-o e execute-o.
7. Compare a resposta de simulação do Paddle com seus registros locais e recibo de webhook persistente.

Use recursos e credenciais sandbox em toda parte. Misturar um segredo de destino ao vivo com uma solicitação de simulador sandbox garante uma falha na assinatura, mesmo que ambas as cordas pareçam plausíveis.

Verificar a Paddle-Signature cabeçalho

Paddle assina cada webhook com o segredo pertencente ao destino de notificação. O cabeçalho contém componentes, incluindo um calendário Unix identificado por ts e uma ou mais assinaturas identificadas por h1. Paddle pode adicionar versões de assinatura, então analisar o cabeçalho em vez de assumir que ele contém um hash nu.

A carga assinada é o timestamp, um cólon, e o corpo pedido intocado. Paddle aplica HMAC-SHA256 com o segredo do endpoint. Sua documentação de verificação da assinatura recomenda um SDK oficial quando disponível e documenta o algoritmo manual. Sempre aplique a tolerância de timestamp do SDK ou uma tolerância explícita em seu verificador para limitar ataques de repetição.

Preferir o SDK oficial em Nó

import express from 'express';
import { Environment, Paddle } from '@paddle/paddle-node-sdk';

const app = express();
const paddle = new Paddle(process.env.PADDLE_API_KEY, {
  environment: Environment.sandbox,
});

app.post(
  '/api/webhooks/paddle',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.header('paddle-signature') ?? '';
    const rawBody = req.body.toString('utf8');

    try {
      const event = await paddle.webhooks.unmarshal(
        rawBody,
        process.env.PADDLE_WEBHOOK_SECRET,
        signature,
      );

      await acceptOnce(event.eventId, event);
      return res.status(200).send('accepted');
    } catch (error) {
      return res.status(400).send('invalid webhook');
    }
  },
);

app.listen(3000);

Montar express.raw() antes de qualquer global express.json() middleware para esta rota. Em um framework estilo Fetch, como Next.js App Router, use await request.text() uma vez e passar essa sequência exata para o SDK. O funcionário webhook quickstart demonstra esta exigência corporal bruta.

Que verificação manual deve fazer

1. Leia o corpo cru sem normalização JSON.
2. Processar cada componente de cabeçalho separado por ponto- e- vírgula e recolher suportado h1 valores.
3. Rejeitar um desaparecido, malformado ou excessivamente velho ts.
4. Calcular HMAC_SHA256(secret, ts + ':' + rawBody).
5. Compare o digest esperado com assinaturas candidatas usando uma comparação de tempo-seguro.
6. Apenas após uma correspondência, analisar JSON e enviar em event_type.

Aceitar quaisquer questões de assinatura válidas suportadas durante a rotação secreta, quando mais de uma assinatura pode estar presente. Não divida o cabeçalho e pegue cegamente o segundo item. Não registre a carga útil secreta ou completa do cliente enquanto diagnostica um descompasso.

Simulações de projeto em torno de invariantes de faturamento

Criação de assinaturas

Execute um cenário de criação de assinatura e verifique se seu banco de dados pode receber eventos de transação e assinatura relacionados sem assumir uma ordem de chegada de rede. Armazene IDs de entidade Paddle e atualize registros de forma idêntica. O pedido deve conceder exatamente um direito, mesmo que um pedido seja ressentido.

Renovação e falha de pagamento

Exercite caminhos de renovação bem-sucedidos, passados e recuperação disponíveis em sua configuração de cenário. Estado de faturamento separado da política de acesso ao produto: seu período de graça pode intencionalmente manter o acesso ativo enquanto Paddle relata um problema de coleta.

Cancelamento e alterações programadas

Distingue uma assinatura programada para cancelar de um que tenha atingido o seu cancelamento efetivo. Preservar next_billed_at, dados de mudança programada, e status do provedor em vez de colapso do ciclo de vida em is_active.

Actualizações da entidade

Simule as atualizações de produto, preço, cliente e assinatura que seu cache consome. Um manipulador deve ignorar tipos de eventos desconhecidos com segurança e reconhecê-los se a assinatura for válida; futuras adições Paddle não devem se transformar em um loop de falha sem fim.

Idempotência e ordenação em cada execução

Use o ID estável do evento webhook como uma chave única em uma tabela de recibos. Em uma transação, insira o recibo, aplique a mudança de estado e coloque efeitos colaterais. Se conflitos de inserção, retornar o sucesso sem repetir o trabalho. Não deduplique apenas por ID de entidade porque muitas atualizações legítimas podem direcionar uma assinatura.

Os eventos podem chegar fora de ordem. Compare o tempo de ocorrência do evento ou recupere a última entidade Paddle antes de aplicar uma transição destrutiva. Armazene o estado e o timestamp do provedor, e rejeite uma atualização antiga que sobrescreveria uma nova. Os cenários de simulação são ideais para testar esses pressupostos, pois produzem sequências conectadas em vez de acessórios isolados.

Resolução de problemas falhas do simulador para a máquina local

O destino retorna 404 ou 405

Verifique se a URL pública inclui a rota completa e que a rota exporta POST. Um navegador GET não é um teste válido de um webhook somente POST. Utilização curl -X POST contra a URL pública para distinguir roteamento de túnel da configuração Paddle.

Destino retorna 400

Inspecionar se Paddle-Signature Chegou e confirma que o segredo do ponto final pertence ao destino de notificação seleccionado. Certifique-se de que nenhum analisador de corpo, registrador de pedido, ou middleware consumido ou reformatado o corpo. O simulador envia assinaturas verificáveis, conforme documentado em Guia de execução de simulação do Paddle.

Destino retorna 500 ou vezes fora

Persista rapidamente e mova chamadas de e-mail, provisionamento e saída API para uma fila. Devolva 2xx após aceitação durável. Jogar em um tipo de evento desconhecido é uma causa comum de falhas desnecessárias; use um branch padrão que grava e reconhece.

O cenário utiliza dados inesperados

Reveja se a simulação utiliza valores gerados automaticamente ou é povoada com entidades reais sandbox. Inspecione as opções de cenário configuradas e a carga útil do evento de execução em vez de assumir que ele espelha uma execução anterior.

Verificação de segurança antes da produção

• Mantenha chaves API e segredos de destino de notificação separados e apenas servidor.
• Verifique o corpo bruto, a assinatura do cabeçalho e o timestamp antes de processar.
• Use uma comparação de tempo seguro ou verificador oficial SDK.
• Desduplicar IDs de eventos e lidar com atualizações fora de ordem.
• Aplique limites corporais, roteamento somente para POST, registro redigido e controles de taxa.
• Use sandbox e destinos ao vivo distintos, depois repita simulações e fluxos reais de sandbox antes de mudar o URL de produção.

O simulador prova sua integração sob sequências de ciclo de vida controladas; um checkout real da sandbox também prova relações de checkout-to-entity. Usar ambos, em seguida, rever o geral guia de assinatura webhook e guia de idempotência Antes do lançamento.