Terima kejadian Stripe di endpoint webhook Anda

Ketika membuat integrasi Stripe, Anda mungkin menginginkan aplikasi menerima kejadian yang berlangsung di akun Stripe, sehingga sistem backend Anda dapat menjalankan tindakan dengan semestinya.

Create an event destination to receive events at an HTTPS webhook endpoint. After you register a webhook endpoint, Stripe can push real-time event data to your application’s webhook endpoint when events happen in your Stripe account. Stripe uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

Menerima kejadian webhook sangat berguna untuk mendengarkan kejadian asinkron seperti saat bank pelanggan mengonfirmasi pembayaran, pelanggan mempersengketakan charge, pembayaran rutin berhasil, atau saat mengumpulkan pembayaran langganan.

You can also receive events in Amazon EventBridge with event destinations.

Mulai

Untuk mulai menerima kejadian webhook di aplikasi Anda, buat dan daftarkan endpoint webhook:

1. Buat handler endpoint webhook untuk menerima permintaan POST data kejadian.
2. Coba handler endpoint webhook Anda secara lokal menggunakan Stripe CLI.
3. Daftarkan endpoint Anda dalam Stripe menggunakan Dashboard atau API.
4. Amankan endpoint webhook Anda.

Anda dapat mendaftarkan dan membuat satu endpoint untuk menangani beberapa tipe kejadian yang berbeda secara bersamaan, atau menyiapkan masing-masing endpoint bagi kejadian spesifik.

require 'json'

# Using Sinatra
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
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Daftarkan endpoint Anda

Setelah mencoba fungsi endpoint webhook Anda, daftarkan URL yang dapat diakses dari endpoint webhook menggunakan bagian Webhook atau API agar Stripe mengetahui ke mana harus mengirimkan kejadian. Anda dapat mendaftarkan hingga 16 endpoint webhook di Stripe. Endpoint webhook yang didaftarkan harus berupa URL HTTPS yang dapat diakses secara publik.

Format URL webhook

Format URL untuk mendaftarkan endpoint webhook adalah:

https://<your-website>/<your-webhook-endpoint>

Misalnya, jika domain Anda adalah https://mycompanysite.com dan rute ke endpoint webhook Anda adalah @app.route('/stripe_webhooks', methods=['POST']), masukkan https://mycompanysite.com/stripe_webhooks sebagai URL Endpoint

Buat endpoint webhook baru

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

Catatan

Workbench menggantikan Dashboard Pengembang yang ada. Jika Anda masih menggunakan Dashboard Pengembang, lihat cara untuk membuat endpoint webhook baru.

Daftarkan endpoint webhook dengan Stripe API

Anda juga dapat secara terprogram membuat endpoint webhook.

Untuk menerima kejadian dari akun terhubung, gunakan parameter Connect.

Contoh berikut ini membuat endpoint yang memberi tahu Anda bila charge berhasil atau gagal.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

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

Lakukan debug integrasi webhook

Beberapa tipe masalah dapat terjadi ketika mengirimkan kejadian ke endpoint webhook Anda:

• Stripe mungkin tidak dapat mengirimkan kejadian ke endpoint webhook Anda.
• Endpoint webhook Anda mungkin memiliki masalah SSL.
• Konektivitas jaringan Anda terputus-putus.
• Endpoint webhook Anda tidak menerima kejadian yang Anda perkirakan.

Lihat pengiriman kejadian

Untuk melihat pengiriman kejadian bagi endpoint spesifik, pilih endpoint webhook di tab Webhook.

Untuk melihat semua kejadian yang dipicu di akun Anda, lihat tab Kejadian.

Perbaiki kode status HTTP

Bila kejadian menampilkan kode status 200, ini menunjukkan pengiriman yang berhasil ke endpoint webhook. Anda mungkin juga menerima kode status selain 200. Lihat tabel di bawah ini untuk daftar kode status HTTP yang umum dan solusi yang direkomendasikan.

Perilaku pengiriman kejadian

Bagian ini membantu Anda memahami berbagai perilaku yang diperkirakan mengenai cara Stripe mengirim kejadian ke endpoint webhook Anda.

Perilaku percobaan ulang

Dalam mode live, Stripe mencoba mengirimkan kejadian tertentu ke endpoint webhook Anda hingga 3 hari dengan backoff eksponensial. Pada bagian Kejadian di Dashboard, Anda dapat melihat kapan percobaan ulang berikutnya akan terjadi.

Dalam mode percobaan, Stripe mencoba ulang tiga kali selama beberapa jam. Anda dapat mencoba ulang mengirimkan masing-masing kejadian secara manual ke endpoint webhook setelah waktu ini menggunakan bagian Kejadian di Dashboard. Anda juga dapat meminta query kejadian yang terlewat untuk melakukan rekonsiliasi data selama jangka waktu tertentu.

Percobaan ulang otomatis masih berlanjut, sekalipun Anda mencoba ulang mengirimkan masing-masing kejadian webhook secara manual ke endpoint tertentu dan upaya tersebut berhasil.

Jika endpoint Anda telah dinonaktifkan atau dihapus saat Stripe mencoba ulang, percobaan ulang mendatang dari kejadian tersebut akan dicegah. Namun, jika Anda menonaktifkan, kemudian mengaktifkan kembali endpoint webhook sebelum kami dapat mencoba ulang, Anda masih dapat melihat upaya percobaan ulang mendatang.

Nonaktifkan perilaku

Dalam mode live dan percobaan, Stripe mencoba memberi tahu Anda tentang endpoint yang salah dikonfigurasi melalui email jika endpoint tidak menanggapi dengan kode status HTTP 2xx selama beberapa hari berturut-turut. Email tersebut juga menyatakan kapan endpoint akan dinonaktifkan secara otomatis.

Pembuatan versi API

Versi API di pengaturan akun Anda saat kejadian berlangsung menentukan versi API sehingga struktur objek Event dikirim di webhook. Misalnya, jika akun Anda diatur ke versi API yang lebih lama, seperti 2015-02-16, dan Anda mengubah versi API untuk permintaan spesifik dengan pembuatan versi, objek Event yang dihasilkan dan dikirim ke endpoint Anda tetap didasarkan pada versi API 2015-02-16.

Anda tidak dapat mengubah objek Event setelah pembuatan. Misalnya, jika Anda memperbarui charge, kejadian charge semula tetap tidak berubah. Hal ini berarti pembaruan berikutnya pada versi API akun Anda tidak secara retroaktif mengubah objek Event yang sudah ada. Pengambilan kejadian yang lebih lama dengan memanggil /v1/events menggunakan versi API yang lebih baru juga tidak memengaruhi struktur kejadian yang diterima.

Anda dapat mengatur endpoint webhook percobaan ke versi API default atau versi API terbaru. Event yang dikirim ke URL webhook disusun untuk versi endpoint yang ditentukan. Anda juga dapat membuat endpoint secara terprogram dengan api_version spesifik.

Pengurutan kejadian

Stripe tidak menjamin pengiriman kejadian sesuai dengan urutan pembuatannya. Sebagai contoh, pembuatan langganan dapat menghasilkan kejadian berikut ini:

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (jika ada charge)

Endpoint Anda seharusnya tidak melihat pengiriman kejadian ini dalam urutan ini, dan perlu menangani pengiriman dengan semestinya. Anda juga dapat menggunakan API untuk mengambil objek yang tidak ada (misalnya, Anda dapat mengambil invoice, charge, dan objek langganan menggunakan informasi dari invoice.paid jika kebetulan Anda menerima kejadian ini terlebih dahulu).

Praktik terbaik menggunakan webhook

Tinjau praktik terbaik ini guna memastikan webhook Anda tetap aman dan berfungsi dengan baik bersama integrasi Anda.

Tangani kejadian duplikat

Terkadang endpoint webhook dapat menerima kejadian yang sama lebih dari satu kali. Anda dapat berhati-hati terhadap resi kejadian yang diduplikasi dengan memasukkan identifikasi kejadian yang telah Anda proses, kemudian tidak memproses kejadian yang sudah dimasukkan.

In some cases, two separate Event objects are generated and sent. To identify these duplicates, use the ID of the object in data.object along with the event.type.

Hanya dengarkan tipe kejadian yang diperlukan oleh integrasi Anda

Konfigurasikan endpoint webhook untuk hanya menerima tipe kejadian yang diperlukan oleh integrasi Anda. Mendengarkan kejadian ekstra (atau semua kejadian) akan membebani server Anda dan kami tidak merekomendasikannya.

Anda dapat mengubah kejadian yang diterima oleh endpoint webhook di Dashboard atau dengan API.

Tangani kejadian secara asinkron

Konfigurasikan handler Anda untuk memproses kejadian yang masuk dengan antrean asinkron. Anda mungkin mengalami masalah skalabilitas jika memilih untuk memproses kejadian secara sinkron. Setiap lonjakan besar dalam pengiriman webhook (misalnya, selama awal bulan ketika semua langganan diperbarui) mungkin mengalahkan host endpoint Anda.

Antrean asinkron memungkinkan Anda memproses kejadian serentak dengan laju yang dapat didukung oleh sistem Anda.

Bebaskan rute webhook dari proteksi CSRF

Jika menggunakan Rails, Django, atau kerangka web lain, situs Anda dapat memeriksa secara otomatis apakah setiap permintaan POST berisi CSRF token. Ini adalah fitur keamanan penting yang membantu memproteksi Anda dan pengguna Anda dari upaya cross-site request forgery. Namun, langkah pengamanan ini juga dapat mencegah situs Anda memproses kejadian yang sah. Jika demikian, Anda mungkin perlu mengecualikan rute webhook dari proteksi CSRF.

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

Terima kejadian dengan server HTTPS

Jika Anda menggunakan URL HTTPS untuk endpoint webhook (diperlukan dalam mode live), Stripe akan memvalidasi keamanan sambungan ke server Anda sebelum mengirim data webhook. Agar hal ini berfungsi, server Anda harus dikonfigurasi dengan benar untuk mendukung HTTPS dengan sertifikat server yang valid. Webhook Stripe hanya mendukung TLS versi v1.2 dan v1.3.

Cabut rahasia penandatanganan endpoint secara berkala

Rahasia yang digunakan untuk memverifikasi bahwa kejadian berasal dari Stripe dapat diubah pada bagian Webhook di Dashboard. Untuk setiap endpoint, klik Cabut rahasia. Anda dapat memilih untuk segera mengakhiri rahasia saat ini atau menunda kedaluwarsanya hingga 24 jam agar Anda memiliki waktu untuk memperbarui kode verifikasi di server Anda. Selama waktu ini, beberapa rahasia aktif untuk endpoint. Stripe membuat satu tanda tangan per rahasia hingga kedaluwarsa. Supaya tetap aman, kami merekomendasikan Anda mencabut rahasia secara berkala, atau bila Anda menduga terjadi peretasan kunci rahasia.

Verifikasikan kejadian dikirim dari Stripe

Stripe mengirim kejadian webhook dari daftar alamat IP yang diatur. Hanya percayai kejadian yang berasal dari alamat IP ini.

Selain itu, verifikasikan tanda tangan webhook untuk mengonfirmasi bahwa kejadian yang diterima telah dikirim dari Stripe. Stripe menandatangani kejadian webhook yang dikirim ke endpoint Anda dengan menyertakan tanda tangan di tajuk Stripe-Signature setiap kejadian. Hal ini memungkinkan Anda memverifikasi bahwa kejadian tersebut dikirim oleh Stripe, bukan oleh pihak ketiga. Anda dapat memverifikasi tanda tangan menggunakan pustaka resmi, atau verifikasikan secara manual menggunakan solusi Anda sendiri.

Bagian berikut menerangkan cara memverifikasi tanda tangan webhook:

1. Ambil rahasia endpoint Anda.
2. Verifikasikan tanda tangan.

Mengambil rahasia endpoint Anda

Gunakan bagian Webhook di Dashboard. Pilih endpoint yang rahasianya ingin Anda peroleh, dan temukan rahasianya pada bagian kanan atas halaman.

Stripe membuatkan kunci rahasia yang unik bagi setiap endpoint. Jika Anda menggunakan endpoint yang sama untuk kunci API percobaan maupun live, rahasia untuk setiap kunci itu berbeda. Selain itu, jika menggunakan beberapa endpoint, Anda harus memperoleh rahasia untuk setiap kunci yang tanda tangannya ingin Anda verifikasi, dan Stripe mulai menandatangani setiap webhook yang dikirim ke endpoint.

Mencegah replay attack

Serangan replay adalah saat penyerang mencegat payload yang valid dan tanda tangannya, kemudian mengirimkannya kembali. Untuk melakukan mitigasi serangan semacam itu, Stripe menyertakan stempel waktu di tajuk Stripe-Signature. Karena merupakan bagian dari payload yang ditandatangani, stempel waktu ini juga diverifikasi oleh tanda tangan, sehingga penyerang tidak dapat mengubah stempel waktu tanpa membatalkan tanda tangan. Jika tanda tangan valid tetapi stempel waktu terlalu lama, aplikasi Anda dapat menolak payload.

Pustaka kami memiliki toleransi default 5 menit antara stempel waktu dan waktu saat ini. Anda dapat mengubah toleransi ini dengan memberikan parameter tambahan ketika memverifikasi tanda tangan. Gunakan Network Time Protocol (NTP) untuk memastikan jam server Anda akurat dan sinkron dengan waktu pada server Stripe.

Stripe membuat stempel waktu dan tanda tangan setiap kali kami mengirim kejadian ke endpoint Anda. Jika Stripe mencoba ulang kejadian (misalnya endpoint Anda yang sebelumnya dibalas dengan kode status non-2xx), maka kami akan membuat tanda tangan dan stempel waktu baru untuk upaya pengiriman baru.

Segera mengembalikan tanggapan 2xx

Endpoint Anda harus segera mengembalikan kode status (2xx) yang berhasil sebelum logika kompleks yang dapat menyebabkan waktu habis. Misalnya, Anda harus mengembalikan respons 200 sebelum memperbarui invoice pelanggan sebagai lunas di sistem akuntansi Anda.