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

Sem um webhook, a aba Detalhes da conversa continua lendo pagamentos e assinaturas ao vivo no Stripe sempre que a conversa é aberta, e os clientes do Stripe são importados como contatos uma vez por dia. Nada fica salvo no Deskwoot entre essas leituras, e um cliente novo no Stripe só vira contato na próxima importação diária.

Adicionar um webhook elimina essa lacuna. O Stripe envia os eventos ao Deskwoot no instante em que eles acontecem na sua conta, e o Deskwoot salva cada cobrança, reembolso e mudança de assinatura na hora. 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. A caixa Eventos de clientes em tempo real mostra a sua URL de webhook pessoal em Passo 1. URL do webhook. Ela se parece com https://deskwoot.com/api/webhooks/stripe-customer/<your-integration-id>. Clique em 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 em Passo 2. Signing secret do webhook e clique em Salvar. O status da caixa Eventos de clientes em tempo real muda de "Não configurado" para "Configurado".

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.

A partir de agora, o Stripe envia novas cobranças, reembolsos, mudanças de assinatura e novos clientes ao Deskwoot no instante em que acontecem, e o Deskwoot os salva na hora, sem esperar pela importação diária de contatos.

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.

Perguntas frequentes