Como integrar os webhooks do Konfiwear no seu carrinho personalizado (passo a passo)

O que irá conseguir

Neste tutorial, irá ligar o Konfiwear a qualquer plataforma que controle — uma loja OpenCart, uma loja personalizada em PHP, uma loja «headless» — utilizando o modo Guardar/API. Quando um cliente terminar de personalizar no configurador 3D e clicar no botão de chamada à ação (CTA), o Konfiwear envia toda a informação da personalização para o seu ponto de extremidade HTTPS: imagens de pré-visualização, preços, detalhes de tamanhos e referências aos ficheiros de produção. A partir daí, o seu código assume o controlo — adicione o artigo ao carrinho, crie uma encomenda, ou faça o que for necessário de acordo com o seu fluxo de trabalho.

Se estiveres no Shopify ou no WooCommerce, não precisas de nada disto — usa, em vez disso, as integrações nativas com o carrinho. O modo «Guardar/API» destina-se a todos os outros.

Requisitos:

• Um espaço de trabalho Konfiwear com acesso ao modo Save/API
• Acesso de administrador às definições do seu espaço de trabalho
• Um ponto final HTTPS acessível publicamente que possa receber pedidos POST

No final, terá:

• O modo Save/API ativado, com a sua URL de webhook configurada e testada
• Verificação de assinatura a proteger o seu ponto de extremidade contra pedidos falsificados
• O seu próprio contexto de sessão a fluir da sua página, passando pelo iframe do personalizador, de volta ao seu servidor

Passo 1 — Ativar o modo Guardar/API

1. No Konfiwear, abre o teu espaço de trabalho da equipa.
2. Vai a Definições → Globais → Chamada para ação.
3. Em Modo de ação, seleciona Guardar / API.
4. No campo URL do Webhook, introduza o seu ponto final HTTPS (por exemplo, https://shop.example.com/konfiwear/webhook).
5. Clique em Enviar teste — o Konfiwear envia uma carga de amostra para o seu ponto de extremidade e mostra-lhe o estado HTTP e o tempo de resposta.
6. Clique em Guardar alterações.

Passo 2 — Compreender a carga útil

Quando um comprador submete um design, o seu endpoint recebe um evento design.saved.v3:

{
  "event": "design.saved.v3",
  "transaction_id": "order-draft-8841",
  "session": {
    "id": "uuid",
    "passthrough": { "s": "o-seu-valor-ecocado" }
  },
  "products": [
    {
      "product": { "code": "jersey", "name": "Jersey" },
      "quote": { "quote_id": "uuid", "quote_number": "QR-1001" },
      "design": { "size_breakdown": { "m": 2, "l": 1 } },
      "pricing": { "unit_price": 42,63, "total": 127,89, "currency": "EUR" },
      "assets": {
        "previews": [{ "status": "ready", "url": "https://..." }],
        "techpack": { "status": "pendente", "url": null }
      }
    }
  ]
}

Eis uma entrega real inspecionada num depurador de webhooks — repare nos cabeçalhos de pedido X-Konfiwear-Event e X-Konfiwear-Signature juntamente com o corpo JSON:

• transaction_id — uma referência que insere no URL do personalizador, que lhe é devolvida (Passo 4).
• session.passthrough — valores adicionais que configurou para serem devolvidos, também provenientes do URL (Passo 4). Apenas presente quando configurado.
• quote_id — o ID único deste envio. Utilize-o para eliminar duplicados.
• assets — imagens de pré-visualização e ficheiros de produção. Os pacotes técnicos e os ficheiros de impressão são gerados em segundo plano; aparecem inicialmente como "pending", e um evento de acompanhamento design.assets.ready é enviado para a mesma URL quando cada ficheiro estiver pronto.

Passo 3 — Verificar assinaturas (recomendado)

Antes de confiar em qualquer informação no corpo de um webhook, confirme se o pedido provém efetivamente da Konfiwear.

Gere o seu segredo: em Definições → Global → Chamada à Ação → Assinatura de webhook, clique em Gerar segredo e copie-o imediatamente — ele é apresentado apenas uma vez. Guarde-o numa variável de ambiente, nunca no seu código ou repositório. Se alguma vez for divulgado, gere-o novamente e atualize o seu ambiente.

$rawBody = file_get_contents('php://input');
$secret  = getenv('KONFIWEAR_WEBHOOK_SECRET');

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$provided = $_SERVER['HTTP_X_KONFIWEAR_SIGNATURE'] ?? '';

if (!hash_equals($expected, $provided)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true); // seguro para processar

import { createHmac, timingSafeEqual } from 'node:crypto';

function isValidSignature(rawBody, header, secret) {
  const expected =
    'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');

  return (
    header?.length === expected.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(header))
  );
}

A única armadilha comum: verifique sempre em relação ao corpo bruto do pedido. Se a sua estrutura analisar primeiro o JSON e o voltar a converter em cadeia de caracteres, o resumo não irá corresponder.

Passo 4 — Incorporar o Customizer e passar o seu próprio contexto

A maioria das integrações Save/API incorpora o Customizer num iframe. O desafio: quando o webhook chega ao seu servidor, como sabe a qual dos seus compradores ele pertence? Não pode confiar no seu cookie de sessão — os navegadores bloqueiam cookies de terceiros dentro de iframes. Em vez disso, passe o seu contexto através do URL e deixe que o Konfiwear o devolva.

Acrescente uma referência à sua escolha ao URL que carrega no iframe:

https://your-domain/c/your-team/jersey?transaction_id=order-draft-8841

O Konfiwear devolve-a na íntegra em cada webhook dessa sessão. Gere-a do lado do servidor, armazene-a associada à sessão do comprador e terá uma chave de junção fiável.

Parâmetros personalizados: passagem de sessão

Se a sua plataforma já produzir um token de sessão com o seu próprio nome de parâmetro (por exemplo, s):

1. Em Definições → Global → Chamada à Ação, adicione o nome do parâmetro aos Parâmetros de passagem de sessão.
2. Acrescente-o ao URL do seu iframe: ...?s=7a6f2ca2f15d3a691aaac9ecbc
3. Recupere-o do webhook em session.passthrough.s.

Apenas os nomes de parâmetros presentes na sua lista de permissões configurada são repetidos — tudo o resto na URL é ignorado. Os nomes design, quote, rev, saved e transaction_id estão reservados.

O Konfiwear também envia uma mensagem do navegador para a sua página principal quando um envio é bem-sucedido (konfiwear:design.saved), para que o seu front-end possa reagir instantaneamente — mostrar uma confirmação, redirecionar para o carrinho — sem ter de consultar o seu servidor.

Passo 5 — Trate o Webhook com Segurança

As boas práticas padrão relativas aos webhooks aplicam-se ao Konfiwear da mesma forma que se aplicam ao Stripe ou ao Shopify:

1. Verifique primeiro a assinatura. A URL do seu webhook é acessível a partir da Internet pública; a assinatura é a chave de segurança. Rejeite tudo o que falhar.
2. Trate os valores devolvidos como chaves de pesquisa, não como autenticação. transaction_id e session.passthrough provêm de um URL no navegador do comprador. Utilize-os para encontrar a sessão correspondente na sua própria loja e confirme que essa sessão foi emitida por si e ainda está ativa — antes de adicionar qualquer item a um carrinho ativo.
3. Valide novamente os preços em relação ao seu próprio catálogo antes de cobrar a qualquer pessoa, da mesma forma que voltaria a verificar quaisquer dados de encomendas recebidas antes de estes entrarem no fluxo de pagamento.
4. Elimine duplicados com base no quote_id para que uma tentativa de entrega repetida não crie uma encomenda duplicada.
5. Confirme rapidamente, processe de forma assíncrona. Tem 10 segundos para devolver um código 2xx — guarde a carga útil, responda com 200 e execute as tarefas mais pesadas (transferências, alterações no carrinho, chamadas ao ERP) num processo em segundo plano.

Em resumo, um manipulador robusto tem o seguinte aspeto:

receber POST
  → verificar a assinatura no corpo bruto          (rejeitar se inválida)
  → eliminar duplicados com base no `quote_id`                      (devolver 200 se já tiver sido visto)
  → procurar o token de passagem na própria loja  (ignorar se desconhecido)
  → persistir a carga útil, enfileirar tarefa em segundo plano
  → devolver 200
tarefa em segundo plano
  → revalidar o preço em relação ao próprio catálogo
  → adicionar artigo ao carrinho / criar encomenda

Resolução de problemas

Pronto para criar?

O modo «Guardar/API» transforma o Konfiwear num front-end de design para qualquer pilha de comércio eletrónico que utilize. Ative-o em Definições → Global → Chamada à Ação, configure a verificação da assinatura e a sua plataforma receberá todos os designs configurados com preços, pré-visualizações e ficheiros de produção anexados.

Comece o seu período de teste gratuito e ligue o Konfiwear à sua plataforma ainda hoje.