Como Configurar Seu Site para Aceitar Webhooks do Stripe

Webhooks permitem que o Stripe envie mensagens de volta para o seu site WordPress. A configuração de webhooks é obrigatória para algumas funcionalidades do WP Simple Pay, como enviar e-mails, criar planos de parcelamento, permitir que os clientes atualizem os detalhes de pagamento de suas assinaturas e usar sua integração com AffiliateWP.

O WP Simple Pay tenta criar endpoints de webhook automaticamente. Na maioria dos casos, a configuração manual, como mostrado abaixo, não será necessária.

Adicionar um Endpoint no Stripe

Para adicionar os endpoints de webhook apropriados, no seu Painel do Stripe, vá para Desenvolvedores → Webhooks.

Clique em Adicionar Endpoint, em seguida, adicione a URL encontrada em WP Simple Pay → Configurações → Stripe → Webhooks.

Não ative Ouvir eventos em Contas Conectadas, pois isso quebrará a funcionalidade de webhook do WP Simple Pay.

Agora você precisará adicionar os eventos específicos para ouvir clicando no botão rotulado +Selecionar eventos. Depois de fazer isso, você pode copiar e colar cada evento listado abaixo na caixa de pesquisa Selecionar eventos para enviar → Pesquisar eventos.

Após pesquisar cada termo, clique na caixa de seleção para adicioná-lo e pesquise termos adicionais. Não clique em Adicionar eventos até ter selecionado todos os eventos listados abaixo:

• payment_intent.processing
• payment_intent.succeeded
• charge.failed
• charge.refunded
• charge.succeeded
• checkout.session.completed
• customer.subscription.deleted
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.upcoming

Detalhes sobre a funcionalidade de cada um desses eventos são mostrados na parte inferior deste documento.

Quando terminar de adicionar eventos, clique em Adicionar endpoint para concluir o processo. Após adicionar o endpoint, você deverá ver a nova URL listada nas configurações de webhooks.

Configurando o Segredo de Assinatura do Webhook

O Stripe pode assinar os eventos de webhook que envia para seus endpoints para maior segurança, e recomendamos fortemente que você configure isso.

Para fazer isso, recupere o segredo do seu endpoint nas configurações de webhooks do seu Painel. Selecione o endpoint adicionado para o qual você deseja obter o segredo e, em seguida, clique no botão Revelar .

Em seguida, copie o segredo de assinatura do Painel do Stripe, volte para WP Simple Pay → Configurações → Stripe → Webhooks no seu admin do WordPress e, em seguida, cole-o na caixa de texto Segredo do Endpoint para o modo de pagamento atual.

Repita no Modo de Teste

Um endpoint de webhook também deve ser criado em Modo de Teste. Alterne o controle deslizante Modo de teste no canto superior direito do painel do Stripe e repita as etapas acima.

Descrições dos Tipos de Evento

invoice.payment_succeeded

• Usado para incrementar planos de parcelamento e enviar e-mails de “Confirmação de Pagamento” e “Notificação de Pagamento” e-mails para Assinaturas.
• Expõe a ação simpay_webhook_subscription_created para processamento adicional após a criação bem-sucedida de uma assinatura.
• Expõe a ação simpay_webhook_invoice_payment_succeeded para processamento adicional após o faturamento ser processado.

<?php
add_action(
	'simpay_webhook_subscription_created',
	/**
	 * Fires when a subscription is created in Stripe.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription.
	 */
	function( $event, $subscription ) {
		// Do something.
	},
	10,
	2
);

<?php
add_action(
	'simpay_webhook_invoice_payment_succeeded',
	/**
	 * Fires when a subscription invoice payment has succeeded.
	 * Does not fire for the subscription creation (first) invoice.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Invoice      $invoice Stripe Invoice object.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription object.
	 */
	function( $event, $invoice, $subscription ) {
		// Do something.
	},
	10,
	3
);

Saiba como adicionar código personalizado →

payment_intent.succeeded

• Envia os e-mails de “Confirmação de Pagamento” e “Notificação de Pagamento” e-mails para pagamentos únicos.
• Expõe a ação simpay_webhook_payment_intent_succeeded para processamento adicional após o pagamento bem-sucedido

<?php
add_action(
	'simpay_webhook_payment_intent_succeeded',
	/**
	 * Fires when a one-time payment has succeeded.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event         $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\PaymentIntent $paymentintent Stripe PaymentIntent.
	 */
	function( $event, $paymentintent ) {
		// Do something.
	},
	10,
	2
);

Saiba como adicionar código personalizado →

invoice.upcoming

• Envia o lembrete de e-mail “Fatura Pendente” e-mail para atualizar um Método de Pagamento. Saiba mais

checkout.session.completed

• Usado para remover registros de checkout abandonados gerados pelo Stripe.
• Expõe a ação simpay_webhook_checkout_session_completed para processamento adicional, se necessário.

charge.succeeded

• Envia os e-mails de “Confirmação de Pagamento” e “Notificação de Pagamento” e-mails para pagamentos únicos usando Débito ACH.
• Expõe a ação simpay_webhook_charge_succeeded para processamento adicional após o pagamento bem-sucedido

charge.failed

• Expõe a ação simpay_webhook_charge_failed para processamento adicional após uma Cobrança falhar.

Perguntas Frequentes

Webhooks são necessários?

Webhooks não são necessários para processar pagamentos, e quando um webhook falha, isso não indica que um pagamento falhou ao ser processado. No entanto, webhooks são utilizados para alimentar funcionalidades como detecção de fraudes, recibos por e-mail, notificações de faturas futuras e gerenciamento de planos de parcelamento.

Webhooks são necessários para utilizar a verificação por e-mail quando a fraude é detectada.

Mesmo que você não esteja usando esses recursos atualmente, é altamente recomendável garantir que você configurou o endpoint do webhook corretamente para evitar confusão se decidir habilitar esses recursos no futuro, ou se o WP Simple Pay exigir essas funcionalidades para recursos futuros.

Por que vejo "O WP Simple Pay pode não estar funcionando corretamente."

O WP Simple Pay tenta alertá-lo sobre possível má configuração ou erro no endpoint do webhook para evitar interrupções em recursos que utilizam a funcionalidade de webhook (e-mails, planos de parcelamento, etc.). Se o WP Simple Pay não conseguir verificar um evento de webhook esperado, você verá uma bolha de notificação nas configurações do plugin e a mensagem de erro "O WP Simple Pay pode não estar funcionando corretamente."

Como corrijo um endpoint de webhook mal configurado?

Para resolver uma possível má configuração do endpoint do webhook, visite Desenvolvedores → Webhooks no seu painel Stripe (se você estiver no Modo de Teste, veja seus endpoints do modo de teste).

Em Endpoints hospedados, você deve ver uma entrada contendo o receptor de webhook do WP Simple Pay: wp-json/wpsp/v1/webhook-receiver. Se você não vir este endpoint, conclua as etapas de configuração descritas no início deste artigo.

Clique no URL do endpoint do WP Simple Pay para ver a configuração do endpoint. Aqui você encontrará uma lista de eventos de webhook que foram enviados ao endpoint.

Clique na guia Falhou para listar quaisquer eventos que falharam.

Se você tiver eventos de webhook com falha, selecionar uma das entradas revelará a resposta recebida do URL do endpoint. Essa resposta geralmente contém informações sobre por que o endpoint falhou ao processar o evento na seção Resposta.

Falha ao conectar ao host remoto

O Stripe não conseguiu se comunicar com seu servidor. Certifique-se de que seu servidor web está respondendo às solicitações e, especificamente, é capaz de responder a quaisquer nomes de domínio totalmente qualificados e endereços IP do Stripe.

Nenhuma assinatura encontrada correspondendo à assinatura esperada para o payload

O Stripe não conseguiu verificar os dados do evento de webhook usando os segredos de assinatura fornecidos em WP Simple Pay → Configurações → Stripe → Webhooks. Ao visualizar seu endpoint de webhook, clique em Revelar em Segredo de Assinatura e atualize suas configurações de segredo de assinatura no WP Simple Pay para cada modo de pagamento.

404 ERRO <!DOCTYPE html>

O URL do endpoint do webhook está incorreto e aponta para uma página 404 não encontrada. Visite WP Simple Pay → Configurações → Stripe → Webhooks para encontrar o valor correto do seu URL de endpoint de webhook e atualize o endpoint no Stripe.

Verifiquei as configurações do meu endpoint, por que ainda estou vendo um erro?

O WP Simple Pay é propositalmente excessivamente responsivo a possíveis configurações incorretas para garantir que um erro real não passe despercebido. No entanto, ainda é possível receber notificações de falso positivo de um evento de webhook mal configurado. Isso pode ocorrer se houver um atraso maior que a média no envio dos dados do evento pelo Stripe, ou em alguns casos do Stripe Checkout, onde a página de pagamento fora do site é abandonada.

Se você verificou que não há eventos de endpoint de webhook falhados em seu endpoint, então você pode desativar a notificação de configuração seguindo os passos abaixo.

Posso desativar as notificações de configuração de webhook?

Como mencionado anteriormente, é altamente recomendável configurar corretamente e manter seu endpoint de webhook habilitado. No entanto, por sua conta e risco, se você não quiser ser alertado sobre quaisquer possíveis configurações incorretas ou eventos recebidos incorretamente, você pode dispensar permanentemente a notificação em WP Simple Pay → Configurações → Stripe → Webhooks clicando em Não mostrar novamente.