# Handle payment events with webhooks

How to use webhooks to respond to offline payment events.

Um *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) é um endpoint HTTP que recebe eventos da Stripe.

Com os webhooks, você pode ser notificado sobre eventos de pagamentos que ocorrem fora do fluxo de pagamento, como:

- Pagamentos bem-sucedidos (`payment_intent.succeeded`)
- Pagamentos contestados (`charge.dispute.created`)
- Saldo disponível na sua conta Stripe (`balance.available`)

Você pode usar o Dashboard para ações avulsas, como reembolsar um pagamento ou atualizar os dados de um cliente. Os webhooks ajudam a ampliar a integração dos pagamentos e processar grandes volumes de eventos cruciais para os negócios.

## Crie seu próprio webhook

Você pode criar um gerenciador de webhooks em seu próprio servidor para gerenciar todos os fluxos de pagamentos offline. Comece expondo um endpoint que receba solicitações da Stripe e use a CLI para testar localmente sua integração. Cada solicitação da Stripe contém um objeto [Event](https://docs.stripe.com/api/events/object.md) com uma referência ao objeto na Stripe que foi modificado.

## Crie um endpoint de webhook

Adicione um novo endpoint no aplicativo. É possível agir em determinados eventos verificando o campo `type` do objeto de evento enviado no corpo da solicitação. Em seguida, você pode imprimir na saída padrão para confirmar o funcionamento do webhook.

Inicie o servidor após adicionar o novo endpoint.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'
require 'json'

# Using the Sinatra framework
set :port, 4242

post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

## Instale e configure a CLI da Stripe
Para obter opções de instalação adicionais, consulte [Comece a usar o Stripe CLI](https://docs.stripe.com/stripe-cli.md).
Depois de instalar a CLI da Stripe, execute `stripe login` na linha de comando para gerar um código de emparelhamento para vincular à sua conta Stripe. Pressione **Enter** para iniciar o navegador e faça login na sua conta Stripe para permitir o acesso. A chave de API gerada é válida por 90 dias, podendo ser modificada ou excluída em [Chaves de API](https://dashboard.stripe.com/apikeys) no Dashboard.

> Você pode criar uma configuração específica para o projeto, incluindo o sinalizador [–project-name](https://docs.stripe.com/cli/login#login-project-name) quando fizer login e executar comandos para esse projeto.

Teste

```bash
stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

Se quiser usar uma chave de API existente, use o sinalizador `--api-key`:

```bash
stripe login --api-key <<YOUR_SECRET_KEY>>
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

## Teste o webhook localmente

Use a CLI para encaminhar eventos ao endpoint do webhook local usando o comando `listen`.

Supondo que o aplicativo está usando a porta 4242, execute:

```bash
stripe listen --forward-to http://localhost:4242/webhook
```

Em uma guia de terminal diferente, use o comando da CLI `trigger` para acionar um evento de webhook simulado.

```bash
stripe trigger payment_intent.succeeded
```

O seguinte evento aparece na sua guia `listen`:

```bash
[200 POST] OK payment_intent.succeeded
```

“O PaymentIntent foi bem-sucedido” aparece na guia do terminal em que o servidor está executando.

## Optional: Verifique a assinatura do webhook

A Stripe inclui uma assinatura no cabeçalho `Stripe-Signature` cada evento. Isso permite verificar se os eventos foram enviados pela Stripe e não por um terceiro. Você pode verificar assinaturas usando nossas bibliotecas oficiais ou [verificar assinaturas manualmente](https://docs.stripe.com/webhooks.md#verify-manually) usando sua própria solução.

Primeiro, encontre o segredo do endpoint do webhook e adicione-o ao gerenciador de webhooks como `endpoint_secret`. Como você ainda está usando a CLI da Stripe para desenvolver o endpoint localmente, use o comando `trigger` para obter da CLI o segredo do endpoint do webhook.

```bash
stripe listen
```

O segredo do endpoint do webhook começa com `whsec_` e é seguido por uma série de números e letras. Mantenha esse segredo do endpoint do webhook em um local seguro e nunca o divulgue publicamente.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboardendpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.readsig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  beginevent = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e# Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

## Implante o endpoint do webhook

Quando estiver pronto para implantar o endpoint do webhook em produção, você precisa fazer o seguinte:

1. Use as [chaves de API do modo de produção](https://docs.stripe.com/keys.md#test-live-modes) e não as chaves de teste.
1. Configure seu endpoint de webhook em [Workbench](https://docs.stripe.com/workbench.md) ou com a API.
1. Para configurar seu endpoint no Workbench, vá para a guia [Webhooks](https://dashboard.stripe.com/workbench/webhooks).
1. Clique em **Adicionar destino** e insira a versão da API Stripe e os eventos específicos que você deseja que a Stripe envie. Clique em **Continuar** e selecione **Endpoint de webhook** na lista de tipos de destino disponíveis. Clique em **Continuar** e insira a URL do seu endpoint, nome opcional e descrição opcional. Clique em **Criar destino**.
1. Substitua o segredo do endpoint do webhook no seu aplicativo pelo novo segredo mostrado na visualização de detalhes de destino no Workbench para seu endpoint.

Seu aplicativo já está pronto para aceitar eventos no modo de produção. Para obter mais informações sobre como configurar seu endpoint de webhook, consulte a API [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md). Para testes em uma área restrita, [consulte o Guia de desenvolvimento](https://docs.stripe.com/webhooks.md).