Configure um webhook do Stripe para que os eventos de clientes cheguem em tempo real

Sem um webhook, o Deskwoot busca os dados dos seus clientes no Stripe uma vez a cada 4 horas por meio de uma sincronização em segundo plano. Um cliente que pagou há 2 minutos e abre o seu chat ao vivo para perguntar sobre esse pedido pode ainda não aparecer na barra lateral da conversa, e o bot de IA também não verá o pedido.

Adicionar um webhook elimina essa lacuna. O Stripe envia os eventos ao Deskwoot no instante em que eles acontecem na sua conta. Este guia mostra cada clique com capturas de tela do painel real do Stripe.

Passo 1: copie a URL do webhook no Deskwoot

Abra Configurações → Integrações → Stripe no Deskwoot. O cartão da integração com o Stripe mostra a sua URL de webhook pessoal. Ela se parece com https://deskwoot.com/api/webhooks/stripe-customer/<your-integration-id>. Clique no botão de copiar ao lado dela.

Passo 2: abra a página de webhooks do Stripe

Faça login em dashboard.stripe.com. No canto inferior esquerdo, clique em Developers e depois em Webhooks no menu que aparece.

Passo 3: adicione um destino e selecione os 8 eventos

Na página de webhooks, clique em Add destination. No assistente:

1. Deixe o Event destination scope em Your account.
2. Vá para a aba All events.
3. No campo de busca, encontre e marque cada um destes 8 eventos:
   • charge.succeeded
   • charge.refunded
   • customer.created
   • customer.updated
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.paid
4. Mantenha a versão da API no padrão do Stripe. Clique em Continue.

Passo 4: escolha o tipo de destino

Selecione Webhook endpoint (normalmente já vem pré-selecionado) e clique em Continue.

Passo 5: configure o destino

Digite Deskwoot como Destination name, cole a URL do webhook que você copiou no passo 1 no campo Endpoint URL e clique em Create destination. A descrição é opcional.

Passo 6: revele e copie o signing secret

O Stripe agora mostra o endpoint de webhook recém-criado com o selo Active. Na coluna da direita, encontre a caixa Signing secret, clique no ícone de olho para revelá-lo e copie o valor que começa com whsec_.

Passo 7: cole o secret de volta no Deskwoot

De volta ao Deskwoot, em Configurações → Integrações → Stripe, cole o valor whsec_ no campo Webhook signing secret e clique em Salvar. O status do cartão da integração muda para "Conectado".

Passo 8: envie um webhook de teste

De volta à página do endpoint de webhook no Stripe, clique em Send test webhook. Escolha charge.succeeded na lista suspensa e clique em Send test webhook. Em poucos segundos, o Stripe mostra uma resposta 200 ao lado do evento de teste. Pronto.

Os agentes do chat ao vivo e o bot de IA passarão a ver novas cobranças, reembolsos e mudanças de assinatura no instante em que chegam ao Stripe, em vez de esperar pelo próximo ciclo de sincronização.

Solução de problemas

O webhook de teste retorna um erro 4xx. Abra o Deskwoot em Configurações → Integrações → Stripe e confirme que o signing secret é exatamente o que o Stripe mostrou, sem espaços no início ou no fim. O secret precisa coincidir para que a verificação de assinatura funcione.

O endpoint mostra um 412 Precondition Failed. O Deskwoot tem a integração, mas ainda não tem nenhum signing secret salvo. Cole o valor whsec_ no campo Webhook signing secret e salve.

Os eventos chegam, mas os clientes ainda não aparecem no Deskwoot. O mais provável é que os eventos selecionados não incluam charge.succeeded ou customer.created. Abra o endpoint de webhook no Stripe, clique em Update details e confirme que toda a lista de eventos acima está selecionada.