درک اولیه از Webhooks با مثال

Webhooks راهی برای یک سرویس خارجی است تا برنامه شما را در مورد رویدادهایی که در سرویس رخ می دهد مطلع کند. به عبارت دیگر، این روشی برای برنامه شما برای دریافت اعلان های بلادرنگ از رویدادهایی است که خارج از برنامه شما اتفاق می افتد.

در زمینه Ruby on Rails، وب هوک ها معمولاً برای ادغام با سرویس های شخص ثالث مانند Stripe، PayPal و دیگران استفاده می شوند. این سرویس ها از webhook ها برای ارسال اعلان ها به برنامه شما در مورد رویدادهایی مانند پرداخت های موفق، پرداخت های ناموفق، مشترکین جدید و رویدادهای دیگر استفاده می کنند.

با استفاده از وب هوک ها در برنامه Ruby on Rails خود، می توانید فرآیندهایی را که در غیر این صورت نیاز به مداخله دستی دارند، مانند به روز رسانی وضعیت حساب کاربر یا ارسال اعلان به کاربران، خودکار کنید. این می تواند تجربه کاربر را بهبود بخشد و گردش کار برنامه شما را ساده کند.

وب هوک ها را می توان با استفاده از پروتکل های مختلفی مانند HTTP، HTTPS و غیره پیاده سازی کرد. در Ruby on Rails، وبک‌هوک‌ها معمولاً با استفاده از اقدامات کنترل‌کننده‌ای که درخواست‌های وب‌هوک را دریافت و پردازش می‌کنند، و کارهای پس‌زمینه برای انجام کار واقعی مدیریت رویدادهای وب هوک، پیاده‌سازی می‌شوند.

به طور کلی، webhooks یک راه قدرتمند برای ادغام برنامه Ruby on Rails شما با خدمات شخص ثالث و خودکارسازی فرآیندها در برنامه شما ارائه می دهد.

مدیریت کارآمد و با مدیریت صحیح خطاها در برنامه Ruby on Rails برای اطمینان از اینکه برنامه شما می‌تواند حجم زیادی از درخواست‌های وب هوک را انجام دهد و خطاهایی را که ممکن است رخ دهد بازیابی کند، مهم است. در این مثال، ما از سرویس پردازش پرداخت محبوب Stripe برای نشان دادن نحوه مدیریت کارآمد و با مدیریت صحیح خطاها در برنامه Ruby on Rails استفاده می‌کنیم.

برپایی
اولین قدم این است که Gem Stripe را نصب کرده و آن را در برنامه Rails خود پیکربندی کنید. می توانید این کار را با افزودن کد زیر به Gemfile خود انجام دهید:
gem 'stripe'

سپس، bundle install را اجرا کنید تا Gem نصب شود و a ایجاد شود config/initializers/stripe.rb فایل برای پیکربندی کلیدهای Stripe API:

Rails.configuration.stripe = {
  publishable_key: ENV['STRIPE_PUBLISHABLE_KEY'],
  secret_key: ENV['STRIPE_SECRET_KEY']
}
Stripe.api_key = Rails.configuration.stripe[:secret_key]

یک کنترلر Webhooks ایجاد کنید
در مرحله بعد، باید یک کنترلر برای رسیدگی به درخواست های وب هوک ایجاد کنید. شما می توانید جدید ایجاد کنید WebhooksController با دستور زیر:
rails generate controller webhooks

در webhooks_controller.rb فایل، یک روش جدید برای رسیدگی به درخواست های وب هوک تعریف کنید:

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def receive
    event = Stripe::Event.construct_from(params.to_unsafe_h)

    # Handle the event
    begin
      case event.type
      when 'payment_intent.succeeded'
        handle_payment_succeeded(event.data.object)
      when 'payment_intent.payment_failed'
        handle_payment_failed(event.data.object)
      else
        raise "Unhandled event type: #{event.type}"
      end
    rescue StandardError => e
      render json: { error: e.message }, status: :unprocessable_entity
    end

    render json: { message: 'Webhook received successfully' }, status: :ok
  end

  private

    def handle_payment_succeeded(payment_intent)
        # Find the user associated with the payment
        user = User.find_by(stripe_customer_id: payment_intent.customer)

        # Check if the payment covers any outstanding invoices
        invoices = user.invoices.unpaid
        invoices.each do |invoice|
            if invoice.amount_due <= payment_intent.amount_received
            invoice.update(status: 'paid', paid_at: Time.now)
            payment_intent.amount_received -= invoice.amount_due
            end
        end

        # Create a new payment record
        payment = Payment.create(
            user: user,
            amount: payment_intent.amount_received,
            payment_method: payment_intent.payment_method,
            payment_intent_id: payment_intent.id,
            status: payment_intent.status,
            paid_at: payment_intent.created
        )

        # Send a confirmation email to the user
        UserMailer.payment_received(user, payment).deliver_later
        rescue => e
         Rails.logger.error("Error handling payment failed webhook: #{e}")
    end

    def handle_payment_failed(payment_intent)
        # Find the user associated with the payment
        user = User.find_by(stripe_customer_id: payment_intent.customer)

        # Handle any unpaid invoices
        invoices = user.invoices.unpaid
        invoices.each do |invoice|
            invoice.update(status: 'failed', failed_at: Time.now)
        end

        # Create a new payment record
        payment = Payment.create(
            user: user,
            amount: payment_intent.amount_received,
            payment_method: payment_intent.payment_method,
            payment_intent_id: payment_intent.id,
            status: payment_intent.status,
            failed_at: payment_intent.created
        )

        # Send a notification email to the user
        UserMailer.payment_failed(user, payment).deliver_later
        rescue => e
         Rails.logger.error("Error handling payment failed webhook: #{e}")
    end
end

ابتدا کاربر مرتبط با پرداخت را با جستجوی شناسه مشتری Stripe آنها پیدا می کنیم. سپس با تکرار صورت‌حساب‌های پرداخت‌نشده کاربر و به‌روزرسانی وضعیت آن‌ها به «پرداخت شده» در صورت کافی بودن مبلغ پرداخت، بررسی می‌کنیم که آیا پرداخت صورت‌حساب‌های معوق را پوشش می‌دهد یا خیر.

سپس یک رکورد پرداخت جدید در پایگاه داده خود با اطلاعاتی از شی payment_intent، از جمله کاربر، مبلغ پرداخت، روش پرداخت، شناسه قصد پرداخت و وضعیت پرداخت ایجاد می کنیم. همچنین مهر زمانی pay_at را روی زمان ایجاد پرداخت تنظیم کردیم.

سپس با جستجوی شناسه مشتری Stripe کاربر مرتبط با پرداخت را پیدا می کنیم. سپس با تکرار صورت‌حساب‌های پرداخت‌نشده کاربر و به‌روزرسانی وضعیت آن‌ها به «ناموفق» با روش به‌روزرسانی، هرگونه فاکتور پرداخت‌نشده را بررسی می‌کنیم.

سپس یک رکورد پرداخت جدید در پایگاه داده خود با اطلاعاتی از شی payment_intent، از جمله کاربر، مبلغ پرداخت، روش پرداخت، شناسه قصد پرداخت و وضعیت پرداخت ایجاد می کنیم. ما همچنین fault_at را روی زمان ایجاد پرداخت تنظیم کردیم.

در نهایت با استفاده از شی UserMailer و روش deliver_later برای ارسال ایمیل به صورت ناهمزمان، یک ایمیل اعلان برای کاربر ارسال می کنیم.

Webhooks را در Stripe پیکربندی کنید
اکنون که برنامه شما برای رسیدگی به درخواست های وب هوک تنظیم شده است، باید حساب Stripe خود را برای ارسال درخواست های وب هوک به برنامه خود پیکربندی کنید. وارد داشبورد Stripe خود شوید و به تب “Webhooks” بروید.

روی دکمه “افزودن نقطه پایان” کلیک کنید و URL را برای عملکرد کنترل کننده وب هوک خود وارد کنید (به عنوان مثال https://example.com/webhooks/receive). می توانید فیلدهای دیگر را با مقادیر پیش فرض خود رها کنید.

در نهایت رویدادهایی را که می خواهید دریافت کنید انتخاب کنید و روی دکمه «افزودن نقطه پایانی» کلیک کنید. Stripe اکنون هر زمان که رویدادهای انتخاب شده رخ دهد، درخواست‌های webhook را به برنامه شما ارسال می‌کند.

آزمایش کردن
برای آزمایش کنترل وب هوک خود، می توانید از Stripe CLI برای شبیه سازی رویدادها استفاده کنید. Stripe CLI را نصب کنید و دستور زیر را اجرا کنید: stripe trigger payment_intent.succeeded

این یک رویداد payment_intent.succeeded را شبیه‌سازی می‌کند و یک درخواست webhook را به برنامه شما ارسال می‌کند. گزارش های برنامه خود را بررسی کنید تا تأیید کنید که وب هوک با موفقیت دریافت و مدیریت شده است.

همچنین می توانید یک پرداخت ناموفق را با اجرای:
stripe trigger payment_intent.payment_failed

این یک رویداد payment_intent.payment_failed را شبیه‌سازی می‌کند و یک درخواست webhook را به برنامه شما ارسال می‌کند. دوباره، گزارش های برنامه خود را بررسی کنید تا تأیید کنید که وب هوک با موفقیت دریافت و مدیریت شده است.

اگر در حین مدیریت وب هوک خطایی رخ داد، گزارش های خود را برای پیام های خطا بررسی کنید و مطمئن شوید که کد رسیدگی به خطا به درستی کار می کند.

همچنین ایده خوبی است که مدیریت وب هوک خود را با سناریوهای مختلفی از جمله پرداخت های موفق و ناموفق، خطاهای شبکه و رویدادهای غیرمنتظره آزمایش کنید.

و بس! اکنون در برنامه Ruby on Rails خود دارای یک سیستم مدیریت وب هوک قوی و کارآمد هستید. با کنترل و آزمایش صحیح خطا، برنامه شما می تواند حجم زیادی از درخواست های وب هوک را مدیریت کند و از خطاهایی که ممکن است رخ دهد بازیابی کند.