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.

Buat tujuan kejadian untuk menerima kejadian di endpoint webhook HTTPS. Setelah mendaftarkan endpoint webhook, Stripe dapat mendorong data kejadian secara aktual ke endpoint webhook aplikasi Anda bila kejadian berlangsung di akun Stripe. Stripe menggunakan HTTPS untuk mengirim kejadian webhook ke aplikasi Anda sebagai payload JSON yang menyertakan objek Kejadian.

Menerima kejadian webhook membantu Anda merespons kejadian asinkron, seperti bila bank pelanggan mengonfirmasi pembayaran, pelanggan mempersengketakan charge, atau pembayaran rutin berhasil.

Anda juga dapat menerima kejadian di Amazon EventBridge dengan tujuan kejadian.

Memulai

Untuk mulai menerima kejadian webhook di aplikasi Anda:

1. Buat handler endpoint webhook untuk menerima permintaan POST data kejadian.
2. Coba handler endpoint webhook Anda secara lokal menggunakan Stripe CLI.
3. Buat tujuan kejadian baru untuk endpoint webhook Anda.
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.

Perilaku tipe kejadian yang tidak didukung untuk tujuan kejadian organisasi

Stripe mengirimkan sebagian besar tipe kejadian secara asinkron; tetapi, untuk tipe kejadian tertentu, Stripe menunggu respons. Ada atau tidaknya respons dari tujuan kejadian secara langsung memengaruhi tindakan Stripe terkait tipe kejadian spesifik ini.

Tujuan organisasi menawarkan dukungan terbatas untuk tipe kejadian yang memerlukan respons:

• Anda tidak dapat berlangganan issuing_authorization.request untuk tujuan organisasi. Sebagai gantinya, siapkan endpoint webhook di akun Stripe dalam organisasi untuk berlangganan tipe kejadian ini. Gunakan issuing_authorization.request untuk mengotorisasi permintaan pembelian secara real-time.
• Anda dapat berlangganan checkout_sessions.completed untuk tujuan organisasi. Namun, hal ini tidak menangani perilaku pengalihan bila Anda menyematkan Checkout secara langsung di situs web atau mengalihkan pelanggan ke halaman pembayaran yang di-hosting Stripe. Mengirimkan kejadian checkout_sessions.completed ke tujuan organisasi tidak akan memengaruhi perilaku pengalihan. Untuk memengaruhi perilaku pengalihan Checkout, proseslah tipe kejadian ini dengan endpoint webhook yang dikonfigurasi di akun Stripe dalam organisasi.
• Anda dapat berlangganan invoice.created untuk tujuan organisasi. Namun, tidak berhasil menanggapi kejadian ini tidak memengaruhi finalisasi invoice otomatis saat menggunakan penagihan otomatis. Untuk memengaruhi finalisasi invoice otomatis melalui respons endpoint webhook, proseslah tipe kejadian ini dengan endpoint webhook yang dikonfigurasi di akun Stripe dalam organisasi.

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

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

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  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, gunakan API atau tab Webhook di Workbench untuk mendaftarkan URL yang dapat diakses dari endpoint webhook Anda sehingga Stripe mengetahui tujuan pengiriman kejadian. Anda dapat mendaftarkan hingga 16 endpoint webhook dengan 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 Endpoint URL.

Buat tujuan kejadian untuk endpoint webhook Anda

Buat tujuan kejadian menggunakan Workbench di Dashboard atau secara terprogram dengan API. Anda dapat mendaftarkan hingga 16 tujuan kejadian di setiap akun Stripe.

Dashboard

API

Untuk membuat endpoint webhook baru di Dashboard:

1. Buka tab Webhook di Workbench.
2. Klik Buat tujuan kejadian.
3. Pilih tempat Anda ingin menerima kejadian. Stripe mendukung dua tipe konfigurasi: Akun Anda dan Akun terhubung. Pilih Akun untuk mendengarkan kejadian dari akun Anda sendiri. Jika Anda membuat aplikasi Connect dan ingin mendengarkan kejadian dari akun terhubung, pilih Akun terhubung.

Dengarkan kejadian dari endpoint webhook organisasi

Jika membuat endpoint webhook di akun organisasi, pilih Akun untuk mendengarkan kejadian dari akun di organisasi Anda. Jika Anda memiliki platform Connect sebagai anggota organisasi dan ingin mendengarkan kejadian dari semua akun terhubung platform, pilih Akun terhubung.

1. Pilih versi API untuk objek kejadian yang ingin Anda gunakan.
2. Pilih tipe kejadian yang ingin Anda kirimkan ke endpoint webhook.
3. Pilih Lanjutkan, lalu pilih Endpoint webhook sebagai tipe tujuan.
4. Klik Lanjutkan, lalu berikan URL endpoint dan deskripsi opsional untuk webhook.

Daftarkan webhook baru menggunakan tab Webhook

Catatan

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

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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

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, pilih endpoint webhook di bawah Webhook, kemudian pilih tab Kejadian.

Tab Kejadian menyediakan daftar kejadian dan apakah kejadian tersebut Delivered, Pending, atau Failed. Klik kejadian untuk melihat Delivery attempts, yang menyertakan kode status HTTP dari upaya pengiriman sebelumnya dan waktu pengiriman mendatang yang menunggu.

Lihat upaya pengiriman kejadian di tab Kejadian endpoint webhook.

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.

Percobaan ulang otomatis

Stripe mencoba untuk mengirim kejadian ke tujuan Anda hingga selama tiga hari dengan backoff eksponensial dalam mode live. Lihat kapan percobaan ulang berikutnya akan terjadi, jika berlaku, di tab Pengiriman kejadian dari tujuan kejadian. Kami mencoba ulang pengiriman kejadian yang dibuat di sandbox tiga kali selama beberapa jam. Jika tujuan Anda telah dinonaktifkan atau dihapus saat kami mencoba ulang, kami mencegah percobaan ulang mendatang dari kejadian tersebut. Namun, jika Anda menonaktifkan, kemudian mengaktifkan ulang tujuan kejadian sebelum kami dapat mencoba ulang, Anda masih melihat upaya percobaan ulang mendatang.

Percobaan ulang manual

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

Pengurutan kejadian

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

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

Pastikan tujuan kejadian Anda tidak bergantung pada penerimaan kejadian dalam urutan spesifik. Bersiaplah mengelola pengiriman sebagaimana mestinya. Anda juga dapat menggunakan API untuk mengambil objek yang tidak ada. Misalnya, Anda dapat mengambil invoice, charge, dan objek langganan dengan informasi dari invoice.paid jika Anda menerima kejadian ini terlebih dahulu.

Pembuatan versi API

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Praktik terbaik menggunakan webhook

Tinjau praktik terbaik ini untuk memastikan endpoint webhook 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.

Dalam beberapa kasus, dua objek Event yang terpisah dihasilkan dan dikirim. Untuk mengidentifikasi duplikat tersebut, gunakan ID objek di data.object bersama dengan 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 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) dapat membanjiri host endpoint Anda.

Antrean asinkron memungkinkan Anda memproses kejadian bersamaan dengan kecepatan yang dapat didukung 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 tab Webhook di Workbench. Supaya tetap aman, kami merekomendasikan Anda mencabut (mengubah) rahasia secara berkala, atau bila Anda menduga terjadi peretasan kunci rahasia.

Untuk mencabut rahasia:

1. Klik setiap endpoint di tab Webhook Workbench yang rahasianya ingin Anda cabut.
2. Masuk ke menu perluasan () dan 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 bagi endpoint. Stripe membuat satu tanda tangan per rahasia hingga kedaluwarsa.

Verifikasikan kejadian dikirim dari Stripe

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

Verifikasikan juga tanda tangan webhook untuk mengonfirmasi bahwa Stripe mengirim kejadian yang diterima. Stripe menandatangani kejadian webhook yang dikirim ke endpoint Anda dengan menyertakan tanda tangan di header Stripe-Signature setiap kejadian. Ini memungkinkan Anda memverifikasi bahwa kejadian 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 Workbench dan masuk ke tab Webhook untuk melihat semua endpoint Anda. Pilih endpoint yang rahasianya ingin Anda peroleh, kemudian klik Klik untuk memperlihatkan.

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. Setelah persiapan ini, 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.