DecisaDocumentação

Docs · Integrações

Conecte uma plataforma de checkout.

Cada integração traz seu próprio receptor de webhook e mapeador canônico. A verificação da assinatura HMAC é obrigatória em toda rota de webhook — sem exceções.

Verificação HMAC, sempre

Toda requisição de webhook precisa passar pela verificação da assinatura HMAC antes que o Decisa grave qualquer coisa no banco de dados. Não aceitamos o compromisso de "simplesmente desativar durante a configuração" — um segredo de webhook incorreto retornará 401 todas as vezes, e a mensagem de diagnóstico informa qual cabeçalho verificar.

O segredo compartilhado fica nas configurações do seu workspace em Integrations → [provider] → Webhook secret. Faça a rotação a qualquer momento; o receptor aceita o segredo anterior por 5 minutos após a rotação, para que as requisições em andamento sobrevivam à transição.

Segurança contra reenvio

Todos os provedores fazem novas tentativas. Partimos do princípio de que a entrega duplicada é o padrão. A idempotência é aplicada em duas camadas:

  • Unicidade de raw_payload em (workspace_id, provider, event_id) — o mesmo webhook não pode criar duas linhas brutas.
  • Unicidade da conversão canônica em (workspace_id, external_id) — mapear diferentes payloads brutos para o mesmo evento de negócio nunca cria duplicatas a jusante.

Provedores suportados

Shopify

Disponível para todos

POST /api/webhooks/shopify

  • orders/create
  • orders/paid
  • orders/refunded

Configure o webhook em Shopify Admin → Settings → Notifications. O Decisa deriva o external_id do id do pedido e o visitor_id do atributo de nota do pedido dcs_vid (preenchido automaticamente pelo pixel no checkout).

Stripe

Disponível para todos

POST /api/webhooks/stripe

  • checkout.session.completed
  • invoice.paid
  • customer.subscription.created

Configure um endpoint de webhook em Stripe Dashboard → Developers → Webhooks. A junção do visitante usa o campo metadata.dcs_vid — defina-o a partir do cliente durante a criação do checkout.

Kiwify

Beta

POST /api/webhooks/kiwify

  • order.approved
  • subscription.renewed
  • order.refunded

Adicione a URL do webhook em Kiwify → Settings → Webhooks. O visitor_id é extraído do parâmetro de query da URL da oferta ?_v=… que o pixel anexa aos links de checkout de saída.

Custom backend

Sempre disponível

POST /v1/conversions

  • Any conversion type

Quando nenhum webhook canônico cobre sua plataforma, chame /v1/conversions diretamente do seu back-end. Consulte a referência da API para o contrato completo do payload.

O que deliberadamente não abstraímos

Não existe uma interface universal de "adaptador de checkout" na base de código. Cada provedor vive em seu próprio namespace (App\Integrations\Checkout\Shopify, etc.) com seu próprio mapeador, seu próprio esquema de payload bruto e sua própria lógica de verificação HMAC. Não vamos extrair um adaptador compartilhado até que três provedores independentes tenham sido lançados e os padrões estejam óbvios.

Isso é intencional. A abstração prematura é o erro mais caro no código de integração — uma vez que você generalizou o formato errado, cada novo provedor vira um quebra-cabeça.

Precisa de um provedor que ainda não lançamos? Escreva para [email protected] com um exemplo de payload de webhook — normalmente lançamos em menos de uma semana. Ou use hoje mesmo o endpoint genérico /v1/conversions a partir do seu back-end.