Consumidores Idempotentes de Webhooks em Ruby on Rails para Eventos Didit (PT-PT)

Garantir a Integridade dos Dados A idempotência é vital para processar eventos de webhook de forma fiável, prevenindo ações duplicadas e mantendo um estado consistente na sua aplicação.

Aproveitar as Assinaturas de Webhook Verifique sempre as assinaturas de webhook para confirmar a autenticidade e integridade dos pedidos recebidos, protegendo contra adulteração e falsificação.

Utilizar IDs de Evento Únicos Armazene e verifique IDs de evento únicos fornecidos nos payloads do webhook para detetar e descartar entregas duplicadas de forma eficaz.

Sistema de Webhooks Robusto da Didit A Didit fornece webhooks seguros e versionados com assinaturas HMAC e IDs de evento únicos, simplificando a implementação de consumidores idempotentes e garantindo a entrega fiável de eventos para fluxos de trabalho críticos de verificação de identidade.

O Desafio da Idempotência de Webhooks

Webhooks são um mecanismo poderoso para comunicação em tempo real entre serviços, permitindo que a sua aplicação reaja instantaneamente a eventos que ocorrem noutro sistema. No entanto, a natureza distribuída dos webhooks significa que os eventos podem, por vezes, ser entregues várias vezes. Falhas de rede, tempos limite ou novas tentativas podem levar a payloads de webhook duplicados. Sem o tratamento adequado, estas duplicações podem causar problemas significativos na sua aplicação, como a criação de registos duplicados, o acionamento de ações redundantes ou a corrupção de dados.

É aqui que a idempotência se torna crítica. Uma operação idempotente é aquela que produz o mesmo resultado, quer seja executada uma vez ou várias vezes. Para consumidores de webhooks, isto significa projetar o seu sistema para processar um determinado evento apenas uma vez, mesmo que o payload do webhook seja recebido várias vezes. Ao lidar com dados sensíveis, como resultados de verificação de identidade de plataformas como a Didit, garantir a idempotência não é apenas uma boa prática — é essencial para manter a integridade dos dados e a fiabilidade do sistema.

Verificar Assinaturas de Webhook para Segurança e Autenticidade

Antes de processar qualquer payload de webhook, o primeiro e mais crítico passo é verificar a sua autenticidade. Isto garante que o webhook realmente se originou do remetente esperado (por exemplo, Didit) e que o seu conteúdo não foi adulterado em trânsito. Os webhooks da Didit, por exemplo, incluem uma assinatura HMAC nos cabeçalhos do pedido, gerada usando uma chave secreta partilhada.

Na sua aplicação Ruby on Rails, precisará de recuperar a chave secreta partilhada da sua conta Didit (que pode aceder através da Consola de Negócios ou programaticamente usando a API). Quando um webhook chega, irá calcular a sua própria assinatura HMAC usando o corpo do pedido e a sua chave secreta. Esta assinatura calculada é então comparada com a assinatura fornecida no cabeçalho do webhook. Se não coincidirem, o pedido deve ser rejeitado imediatamente.

class DiditWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    # Retrieve the shared secret key from your environment variables
    secret = ENV['DIDIT_WEBHOOK_SECRET']
    payload = request.body.read
    signature = request.headers['X-Didit-Signature'] # Or similar header name

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

    # Process the webhook payload after verification
    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)
    # ... implementation for processing ...
  end
end

A Didit simplifica isto ao fornecer uma secret_shared_key como parte da sua configuração de webhook, que pode ser recuperada via API ou rodada conforme necessário. Este mecanismo seguro é fundamental para qualquer fluxo de trabalho de verificação de identidade, onde a integridade dos resultados, como os de Verificação de ID ou verificações de Vivacidade, é primordial.

Implementar Idempotência com Identificadores de Evento Únicos

Depois de verificar a autenticidade do webhook, o próximo passo é garantir a idempotência. A maioria dos sistemas de webhook bem projetados, incluindo o da Didit, fornece um identificador único para cada evento. Este ID é crucial para detetar e prevenir o processamento duplicado. Para os webhooks da Didit (especialmente a v3, que é recomendada), cada payload de evento inclui um ID único que pode usar para este fim.

A estratégia é armazenar estes IDs de evento na sua base de dados e verificá-los antes do processamento. Um padrão comum envolve a criação de um modelo EventLog ou 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

Quando um webhook chega:

1. Extraia o event_id único do payload.
2. Tente criar um novo registo WebhookEvent com este event_id.
3. Se a criação falhar devido a uma violação de restrição única (o que significa que o event_id já existe), então sabe que é um duplicado e pode ignorá-lo com segurança ou registá-lo como tal.
4. Se a criação for bem-sucedida, prossiga para processar o evento, marcando o seu estado de acordo.

class DiditWebhooksController < ApplicationController
  # ... (signature verification as above) ...

  def create
    # ... (signature verification) ...

    event_data = JSON.parse(payload)
    event_id = event_data['id'] # Assuming 'id' is the unique event identifier from Didit

    # Use a transaction to ensure atomicity
    ActiveRecord::Base.transaction do
      webhook_event = WebhookEvent.find_or_initialize_by(event_id: event_id)

      if webhook_event.persisted? # If it already exists, it's a duplicate
        Rails.logger.info "Duplicate webhook event received: #{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!

      # Process the event in a background job for long-running tasks
      DiditEventProcessorJob.perform_later(webhook_event.id)
      head :ok
    end
  rescue ActiveRecord::RecordNotUnique # Handle race conditions for event_id
    Rails.logger.warn "Race condition detected for webhook event: #{event_id}. Ignoring."
    head :ok
  rescue JSON::ParserError
    head :bad_request
  rescue => e
    Rails.logger.error "Error processing webhook: #{e.message}"
    head :internal_server_error
  end
end

Esta abordagem, combinada com tarefas em segundo plano para o processamento real, garante que o seu endpoint de webhook responde rapidamente, prevenindo novas tentativas do remetente, enquanto lida de forma fiável com duplicados.

Gerir Condições de Corrida e Transações

Mesmo com um índice único, condições de corrida podem ocorrer se dois webhooks idênticos chegarem quase simultaneamente. Ambos podem tentar criar um novo registo WebhookEvent antes que o primeiro conclua a sua transação. Para mitigar isto:

• Use Transações de Base de Dados: Envolva a lógica find_or_initialize_by e subsequente processamento dentro de uma transação de base de dados. Isto garante que toda a operação é bem-sucedida ou falha, mantendo a consistência dos dados.
• Lidar com RecordNotUnique: Esteja preparado para capturar exceções ActiveRecord::RecordNotUnique. Se esta exceção ocorrer ao tentar guardar um novo WebhookEvent, significa uma condição de corrida onde outro processo já inseriu o evento, e pode tratá-lo com segurança como um duplicado.

Para operações que modificam dados centrais da aplicação, estender a transação para cobrir essas alterações é crucial, ou pelo menos garantir que a tarefa em segundo plano que processa o evento também implementa as suas próprias verificações de idempotência nos dados da aplicação que modifica.

Como a Didit Ajuda

A Didit é uma plataforma de identidade nativa de IA e focada no desenvolvedor, projetada com fiabilidade e segurança em mente, tornando mais fácil implementar consumidores de webhook robustos. A nossa arquitetura modular fornece APIs limpas e webhooks seguros que são inerentemente projetados para suportar o processamento idempotente.

• Webhooks Seguros: Os webhooks da Didit fornecem fortes assinaturas HMAC (usando uma secret_shared_key que pode gerir e rodar) para garantir a autenticidade e integridade de cada evento. Este primeiro passo crucial na idempotência está incorporado. Pode até especificar a webhook_version (v3 recomendada) para uma estrutura de payload ideal.
• Identificadores de Evento Únicos: Cada evento de webhook da Didit inclui um identificador único, tornando simples implementar a lógica de deduplicação discutida acima.
• Retenção de Dados Configurável: Com a Didit, controla por quanto tempo os dados de verificação são armazenados. Pode definir políticas de retenção de dados de 1 mês a 10 anos, ou mesmo nulo para ilimitado, diretamente na Consola de Negócios ou via API. Isto permite-lhe cumprir os requisitos de conformidade (como o RGPD) enquanto gere a sua pegada de dados. Isto também se relaciona com a forma como o seu consumidor de webhook pode armazenar e gerir registos de eventos.
• KYC Core Gratuito e Design Modular: A Didit oferece KYC Core Gratuito, permitindo-lhe começar a construir e testar os seus consumidores de webhook sem custos iniciais. O nosso design modular significa que pode integrar facilmente produtos específicos de verificação de identidade — como Verificação de ID para verificações de documentos, Vivacidade Passiva e Ativa para prevenção de fraude, ou Estimativa de Idade para verificação de idade — e receber atualizações em tempo real via webhooks.

Ao alavancar o sistema de webhook robusto e seguro da Didit, os desenvolvedores podem focar-se mais na lógica central da sua aplicação e menos nas complexidades de proteger e deduplicar eventos recebidos, levando a fluxos de trabalho de verificação de identidade mais resilientes e fiáveis.

Pronto para Começar?

Pronto para ver a Didit em ação? Obtenha uma demonstração gratuita hoje.

Comece a verificar identidades gratuitamente com o nível gratuito da Didit.