# Gerencie eventos de pagamento com webhooks

Como usar webhooks para responder a eventos de pagamento offline.

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

Instale o Stripe CLI com o [npm](https://www.npmjs.com/):

```bash
npm install --global @stripe/cli
```

> Para conferir mais opções de instalação para Windows, macOS, Linux e Docker, consulte o arquivo [readme do Stripe CLI](https://github.com/stripe/stripe-cli#installation) no GitHub.

Após a instalação, faça login para conectar o CLI à sua conta Stripe:

```bash
stripe login
```

A CLI exibe um código de pareamento e abre o Dashboard da Stripe, onde você aprova o acesso a contas, áreas restritas e ao modo de produção. A CLI armazena suas credenciais no armazenamento seguro de credenciais do seu sistema operacional (quando disponível) e atualiza a sessão automaticamente. Para autenticar com uma chave de API, execute `stripe login --interactive`, use `stripe config`, passe `--api-key` ou defina a variável de ambiente `STRIPE_API_KEY`.

## 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 Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

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

  begin
    event = 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.
2. Configure seu endpoint de webhook em [Workbench](https://docs.stripe.com/workbench.md) ou com a API.
3. Para configurar seu endpoint no Workbench, vá para a guia [Webhooks](https://dashboard.stripe.com/workbench/webhooks).
4. 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**.
5. 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).