Konsumen Webhook Idempoten di Ruby on Rails untuk Event Didit (ID)

Memastikan Integritas DataIdempotensi sangat penting untuk memproses event webhook secara andal, mencegah tindakan duplikat, dan menjaga status yang konsisten dalam aplikasi Anda.

Memanfaatkan Tanda Tangan WebhookSelalu verifikasi tanda tangan webhook untuk mengonfirmasi keaslian dan integritas permintaan yang masuk, melindungi dari perusakan dan pemalsuan.

Menggunakan ID Event UnikSimpan dan periksa ID event unik yang disediakan dalam payload webhook untuk mendeteksi dan membuang pengiriman duplikat secara efektif.

Sistem Webhook Didit yang TangguhDidit menyediakan webhook yang aman dan berversi dengan tanda tangan HMAC dan ID event unik, menyederhanakan implementasi konsumen idempoten dan memastikan pengiriman event yang andal untuk alur kerja verifikasi identitas yang penting.

Tantangan Idempotensi Webhook

Webhook adalah mekanisme yang ampuh untuk komunikasi real-time antar layanan, memungkinkan aplikasi Anda bereaksi secara instan terhadap event yang terjadi di sistem lain. Namun, sifat terdistribusi webhook berarti bahwa event terkadang dapat dikirim beberapa kali. Gangguan jaringan, batas waktu, atau percobaan ulang semuanya dapat menyebabkan payload webhook duplikat. Tanpa penanganan yang tepat, duplikat ini dapat menyebabkan masalah signifikan dalam aplikasi Anda, seperti membuat catatan duplikat, memicu tindakan berlebihan, atau merusak data.

Di sinilah idempotensi menjadi sangat penting. Operasi idempoten adalah operasi yang menghasilkan hasil yang sama baik dieksekusi sekali atau beberapa kali. Untuk konsumen webhook, ini berarti merancang sistem Anda untuk memproses event tertentu hanya sekali, bahkan jika payload webhook diterima beberapa kali. Ketika berhadapan dengan data sensitif seperti hasil verifikasi identitas dari platform seperti Didit, memastikan idempotensi bukan hanya praktik yang baik—tetapi juga penting untuk menjaga integritas data dan keandalan sistem.

Memverifikasi Tanda Tangan Webhook untuk Keamanan dan Keaslian

Sebelum memproses payload webhook apa pun, langkah pertama dan paling penting adalah memverifikasi keasliannya. Ini memastikan bahwa webhook benar-benar berasal dari pengirim yang diharapkan (misalnya, Didit) dan bahwa kontennya belum dirusak selama transit. Webhook Didit, misalnya, menyertakan tanda tangan HMAC di header permintaan, yang dihasilkan menggunakan kunci rahasia bersama.

Dalam aplikasi Ruby on Rails Anda, Anda perlu mengambil kunci rahasia bersama dari akun Didit Anda (yang dapat Anda akses melalui Konsol Bisnis atau secara terprogram menggunakan API). Ketika webhook tiba, Anda akan menghitung tanda tangan HMAC Anda sendiri menggunakan isi permintaan dan kunci rahasia Anda. Tanda tangan yang dihitung ini kemudian dibandingkan dengan tanda tangan yang disediakan di header webhook. Jika tidak cocok, permintaan harus segera ditolak.

class DiditWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    # Ambil kunci rahasia bersama dari variabel lingkungan Anda
    secret = ENV['DIDIT_WEBHOOK_SECRET']
    payload = request.body.read
    signature = request.headers['X-Didit-Signature'] # Atau nama header serupa

    unless verify_signature(payload, signature, secret)
      head :unauthorized
      return
    end

    # Proses payload webhook setelah verifikasi
    process_didit_event(JSON.parse(payload))
    head :ok
  end

  private

  def verify_signature(payload, signature, secret)
    digest = OpenSSL::Digest.new('sha256')
    hmac = OpenSSL::HMAC.hexdigest(digest, secret, payload)
    ActiveSupport::SecurityUtils.secure_compare("sha256=#{hmac}", signature)
  end

  def process_didit_event(event_data)
    # ... implementasi untuk pemrosesan ...
  end
end

Didit menyederhanakannya dengan menyediakan secret_shared_key sebagai bagian dari konfigurasi webhook-nya, yang dapat diambil melalui API atau dirotasi sesuai kebutuhan. Mekanisme aman ini sangat mendasar untuk setiap alur kerja verifikasi identitas, di mana integritas hasil, seperti dari Verifikasi ID atau pemeriksaan Liveness, adalah yang terpenting.

Menerapkan Idempotensi dengan Pengidentifikasi Event Unik

Setelah Anda memverifikasi keaslian webhook, langkah selanjutnya adalah memastikan idempotensi. Sebagian besar sistem webhook yang dirancang dengan baik, termasuk Didit, menyediakan pengidentifikasi unik untuk setiap event. ID ini sangat penting untuk mendeteksi dan mencegah pemrosesan duplikat. Untuk webhook Didit (terutama v3, yang direkomendasikan), setiap payload event menyertakan ID unik yang dapat Anda gunakan untuk tujuan ini.

Strateginya adalah menyimpan ID event ini di database Anda dan memeriksanya sebelum memproses. Pola umum melibatkan pembuatan model EventLog atau WebhookEvent:

# db/migrate/YYYYMMDDHHMMSS_create_webhook_events.rb
class CreateWebhookEvents < ActiveRecord::Migration[7.x]
  def change
    create_table :webhook_events do |t|
      t.string :event_id, null: false, index: { unique: true }
      t.string :event_type
      t.jsonb :payload
      t.string :status, default: 'pending'
      t.timestamps
    end
  end
end

Saat webhook tiba:

1. Ekstrak event_id unik dari payload.
2. Coba buat catatan WebhookEvent baru dengan event_id ini.
3. Jika pembuatan gagal karena pelanggaran batasan unik (yang berarti event_id sudah ada), maka Anda tahu itu duplikat dan dapat dengan aman mengabaikannya atau mencatatnya.
4. Jika pembuatan berhasil, lanjutkan untuk memproses event, tandai statusnya sesuai.

class DiditWebhooksController < ApplicationController
  # ... (verifikasi tanda tangan seperti di atas) ...

  def create
    # ... (verifikasi tanda tangan) ...

    event_data = JSON.parse(payload)
    event_id = event_data['id'] # Mengasumsikan 'id' adalah pengidentifikasi event unik dari Didit

    # Gunakan transaksi untuk memastikan atomisitas
    ActiveRecord::Base.transaction do
      webhook_event = WebhookEvent.find_or_initialize_by(event_id: event_id)

      if webhook_event.persisted? # Jika sudah ada, itu duplikat
        Rails.logger.info "Event webhook duplikat diterima: #{event_id}"
        head :ok
        return
      end

      webhook_event.event_type = event_data['type']
      webhook_event.payload = event_data
      webhook_event.status = 'processing'
      webhook_event.save!

      # Proses event dalam pekerjaan latar belakang untuk tugas yang berjalan lama
      DiditEventProcessorJob.perform_later(webhook_event.id)
      head :ok
    end
  rescue ActiveRecord::RecordNotUnique # Tangani kondisi balapan untuk event_id
    Rails.logger.warn "Kondisi balapan terdeteksi untuk event webhook: #{event_id}. Mengabaikan."
    head :ok
  rescue JSON::ParserError
    head :bad_request
  rescue => e
    Rails.logger.error "Kesalahan saat memproses webhook: #{e.message}"
    head :internal_server_error
  end
end

Pendekatan ini, dikombinasikan dengan pekerjaan latar belakang untuk pemrosesan aktual, memastikan bahwa titik akhir webhook Anda merespons dengan cepat, mencegah percobaan ulang dari pengirim, sambil menangani duplikat dengan andal.

Menangani Kondisi Balapan dan Transaksi

Bahkan dengan indeks unik, kondisi balapan dapat terjadi jika dua webhook identik tiba hampir bersamaan. Keduanya mungkin mencoba membuat catatan WebhookEvent baru sebelum yang pertama melakukan transaksinya. Untuk mitigasi ini:

• Gunakan Transaksi Database: Bungkus logika find_or_initialize_by dan pemrosesan selanjutnya dalam transaksi database. Ini memastikan bahwa seluruh operasi berhasil atau gagal, menjaga konsistensi data.
• Tangani RecordNotUnique: Bersiaplah untuk menangkap pengecualian ActiveRecord::RecordNotUnique. Jika pengecualian ini terjadi saat mencoba menyimpan WebhookEvent baru, itu menandakan kondisi balapan di mana proses lain telah memasukkan event tersebut, dan Anda dapat dengan aman memperlakukannya sebagai duplikat.

Untuk operasi yang memodifikasi data aplikasi inti, memperluas transaksi untuk mencakup perubahan tersebut sangat penting, atau setidaknya memastikan bahwa pemrosesan pekerjaan latar belakang event juga mengimplementasikan pemeriksaan idempotensinya sendiri pada data aplikasi yang dimodifikasinya.

Bagaimana Didit Membantu

Didit adalah platform identitas berbasis AI, yang mengutamakan pengembang, dirancang dengan keandalan dan keamanan, sehingga lebih mudah untuk mengimplementasikan konsumen webhook yang tangguh. Arsitektur modular kami menyediakan API yang bersih dan webhook yang aman yang secara inheren dirancang untuk mendukung pemrosesan idempoten.

• Webhook Aman: Webhook Didit menyediakan tanda tangan HMAC yang kuat (menggunakan secret_shared_key yang dapat Anda kelola dan rotasi) untuk memastikan keaslian dan integritas setiap event. Langkah pertama yang krusial dalam idempotensi ini sudah terpasang. Anda bahkan dapat menentukan webhook_version (v3 direkomendasikan) untuk struktur payload yang optimal.
• Pengidentifikasi Event Unik: Setiap event webhook Didit menyertakan pengidentifikasi unik, membuatnya mudah untuk mengimplementasikan logika deduplikasi yang dibahas di atas.
• Retensi Data yang Dapat Dikonfigurasi: Dengan Didit, Anda mengontrol berapa lama data verifikasi disimpan. Anda dapat mengatur kebijakan retensi data dari 1 bulan hingga 10 tahun, atau bahkan nol untuk tidak terbatas, langsung di Konsol Bisnis atau melalui API. Ini memungkinkan Anda untuk memenuhi persyaratan kepatuhan (seperti GDPR) sambil mengelola jejak data Anda. Ini juga terkait dengan bagaimana konsumen webhook Anda mungkin menyimpan dan mengelola log event.
• KYC Inti Gratis & Desain Modular: Didit menawarkan KYC Inti Gratis, memungkinkan Anda untuk mulai membangun dan menguji konsumen webhook Anda tanpa biaya di muka. Desain modular kami berarti Anda dapat dengan mudah mengintegrasikan produk verifikasi identitas tertentu—seperti Verifikasi ID untuk pemeriksaan dokumen, Liveness Pasif & Aktif untuk pencegahan penipuan, atau Estimasi Usia untuk verifikasi usia—dan menerima pembaruan real-time melalui webhook.

Dengan memanfaatkan sistem webhook Didit yang tangguh dan aman, pengembang dapat lebih fokus pada logika inti aplikasi mereka dan lebih sedikit pada kompleksitas mengamankan dan mendeduplikasi event yang masuk, menghasilkan alur kerja verifikasi identitas yang lebih tangguh dan tepercaya.

Siap Memulai?

Siap melihat Didit beraksi? Dapatkan demo gratis hari ini.

Mulai verifikasi identitas secara gratis dengan tingkat gratis Didit.