Pular para o conteúdo principal

Configurar o webhook do Stripe

Se ligou o Stripe através de Connect with Stripe, esta página guia-o pelo único passo manual que o Stripe exige a seguir: criar você mesmo um endpoint de webhook no seu próprio painel Stripe, ecrã a ecrã.

Antes de começar​

  • Isto aplica-se apenas ao Connect with Stripe. Se ligou o Stripe introduzindo você mesmo a sua Chave secreta e Chave pública (ver Pagamentos — Ligar o Stripe), o Agon regista o webhook automaticamente e não precisa desta página.
  • Porque tem de fazer isto você mesmo: o Stripe não permite que uma conta ligada por OAuth ("Connect") registe endpoints de webhook automaticamente — é uma restrição do lado do Stripe, não uma limitação do Agon. Só precisa de o fazer uma vez.
  • Tenha à mão o URL de webhook do seu estúdio. É apresentado no Agon em Definições → Faturação, e tem o aspeto https://studio-<id-do-seu-estudio>.agon-studio.dev/api/billing/webhook — exclusivo do seu estúdio. Mantenha essa página aberta noutra janela ou separador para a poder copiar no passo 7.

Passos​

  1. Abra o seu painel Stripe e aceda a Developers → Webhooks — ou diretamente a Workbench → Webhooks.

  2. Clique em Add destination.

    Página de Webhooks do Workbench Stripe com o botão Add destination

  3. O Stripe abre um assistente Create an event destination em três passos: Select events → Choose destination type → Configure your destination.

  4. Em Select events, em Event destination scope, escolha Your account — não Connected accounts, que se destina apenas a plataformas que recebem eventos das contas Stripe de outras pessoas. O seu estúdio é esta conta. Em Payload style, mantenha Snapshot selecionado — não Thin; o Agon precisa do objeto de evento completo, não apenas de um id que teria de consultar depois. Deixe API version no valor predefinido proposto pelo Stripe.

    Configure your event destination: Your account e Snapshot selecionados

  5. Ainda em Select events, utilize a caixa de pesquisa Find event by name or description… — muito mais rápido do que percorrer toda a árvore de categorias — e selecione exatamente estes 6 eventos, um de cada vez:

    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.paid
    • invoice.payment_failed

    Caixa de pesquisa de eventos: Find event by name or description

    Depois de selecionar os 6, clique em Continue.

  6. Em Choose destination type, selecione Webhook endpoint — a primeira opção. As outras duas, Amazon EventBridge e Azure Event Grid, servem para encaminhar eventos para a sua própria infraestrutura cloud e não se aplicam aqui. Clique em Continue.

    Choose destination type com Webhook endpoint selecionado

  7. Em Configure your destination, o Stripe mostra um resumo das suas escolhas (Events from: Your account, Payload style: Snapshot, Listening to: 6 events), seguido de três campos:

    • Destination name — opcional, qualquer nome serve (por exemplo "Agon"). Serve apenas como referência no seu painel Stripe e não tem qualquer efeito funcional.
    • Endpoint URL — cole aqui o URL de webhook do seu estúdio a partir da página Definições → Faturação do Agon, exatamente como é apresentado. Não o digite à mão — um único erro de digitação faz com que o Stripe nunca consiga alcançar o seu estúdio.
    • Description — opcional, pode ficar em branco.

    Clique no botão para criar o destino.

    Configure destination com os campos Destination name, Endpoint URL e Description

  8. O Stripe mostra agora um Signing secret para o seu novo destino, por vezes atrás de um controlo "reveal" em que é preciso clicar primeiro. Copie-o.

  9. No Agon, aceda a Definições → Faturação e cole-o no campo Segredo do webhook — o mesmo campo descrito em Pagamentos — Ligar o Stripe, sempre visível nessa página e não escondido atrás de uma opção adicional. Clique em Salvar.

E se algo correr mal?​

Não sei se devo escolher "Your account" ou "Connected accounts"

Escolha Your account. O seu estúdio é a conta Stripe que está a configurar — Connected accounts só se aplica se fosse uma plataforma a receber eventos das contas Stripe separadas de outras pessoas, o que não é o caso aqui.

Os meus pagamentos continuam a aparecer como Pendentes depois desta configuração

Verifique se o Endpoint URL foi colado exatamente, sem carateres a mais nem segmentos em falta, e se o Segredo do webhook guardado em Definições → Faturação corresponde ao signing secret que o Stripe mostra para este destino específico. Veja também Pagamentos — E se algo correr mal?.

Preciso de adicionar um evento mais tarde ou de alterar o URL

Reabra o destino em Workbench → Webhooks no seu painel Stripe e edite-o aí. Só precisa de atualizar alguma coisa no Agon se o signing secret também mudar.

Páginas relacionadas​