Создание слушателя Didit Webhook с Fastify и PostgreSQL (RU)

Безопасная интеграция веб-хуковРеализация проверки подписи HMAC-SHA256 критически важна для обеспечения подлинности и целостности данных веб-хуков Didit, защищая ваше приложение от поддельных запросов и поддерживая безопасность данных.

Обработка данных в реальном времениИспользуйте веб-хуки для получения мгновенных уведомлений об изменениях статуса сессии проверки личности, что позволяет вашему приложению немедленно реагировать и автоматизировать процессы регистрации пользователей или управления рисками.

Масштабируемое хранилище данныхИспользуйте PostgreSQL для эффективного хранения и управления данными веб-хуков, что обеспечивает надежные запросы, аудит и интеграцию с вашими существующими системами управления пользователями, гарантируя постоянство и надежность данных.

Модульное преимущество DiditМодульная платформа идентификации Didit и комплексная система веб-хуков упрощают интеграцию, предоставляя разработчикам чистые API и потоки данных в реальном времени для создания гибких, основанных на ИИ решений KYC с бесплатным базовым KYC и без платы за настройку.

Понимание веб-хуков Didit и их важности

В мире проверки личности обратная связь в реальном времени имеет первостепенное значение. Будь то регистрация новых пользователей, предотвращение мошенничества или обеспечение соответствия требованиям, знание статуса сессии проверки в момент ее возникновения критически важно. Здесь на помощь приходят веб-хуки. Веб-хуки Didit предоставляют автоматизированный способ получения уведомлений о событиях, происходящих в ваших рабочих процессах проверки личности, таких как завершение, сбой или необходимость дальнейших действий.

Вместо постоянного опроса API Didit на предмет обновлений, что может быть неэффективным и приводить к задержкам, веб-хуки отправляют данные непосредственно на вашу настроенную конечную точку. Эта событийно-ориентированная архитектура гарантирует, что ваше приложение всегда имеет самую актуальную информацию, позволяя немедленную обработку и более плавный пользовательский опыт. Например, как только пользователь успешно завершает проверку ID Didit и пассивную и активную проверку живости, веб-хук может мгновенно запустить следующий шаг в вашем процессе регистрации.

Didit предлагает настраиваемые версии веб-хуков, причем v3 является рекомендуемым стандартом благодаря своей комплексной структуре полезной нагрузки. Вы можете установить URL веб-хука, версию и даже определить политики хранения данных непосредственно через консоль Didit Business Console или через API, что дает вам полный контроль над потоком данных и обязательствами по соблюдению требований.

Настройка слушателя веб-хуков Fastify

Fastify — это быстрый веб-фреймворк с низкими накладными расходами для Node.js, что делает его отличным выбором для создания высокопроизводительных слушателей веб-хуков. Вот как начать:

1. Настройка проекта и зависимости

Сначала инициализируйте свой проект Node.js и установите необходимые пакеты:

mkdir didit-webhook-listener
cd didit-webhook-listener
npm init -y
npm install fastify dotenv pg crypto

Создайте файл .env для хранения секретного ключа веб-хука Didit и данных подключения PostgreSQL:

DIDIT_WEBHOOK_SECRET=your_didit_webhook_secret_key
DATABASE_URL=postgresql://user:password@host:port/database

Вы можете получить свой DIDIT_WEBHOOK_SECRET из консоли Didit Business Console в разделе «Настройки приложения» или через API Didit, используя конечную точку GET /v3/webhook/.

2. Конфигурация сервера Fastify

Создайте файл app.js. Fastify нуждается в необработанном теле для проверки подписи, поэтому мы настроим его так, чтобы он не анализировал JSON автоматически для нашего маршрута веб-хука.

require('dotenv').config();
const fastify = require('fastify')({ logger: true });
const crypto = require('crypto');
const { Client } = require('pg');

const DIDIT_WEBHOOK_SECRET = process.env.DIDIT_WEBHOOK_SECRET;
const DATABASE_URL = process.env.DATABASE_URL;

const pgClient = new Client({ connectionString: DATABASE_URL });

// Register a content parser for 'application/json' that leaves the body raw for specific routes
fastify.addContentTypeParser('application/json', { parseAs: 'buffer' }, function (req, body, done) {
  if (req.raw.url === '/webhooks/didit') {
    done(null, body); // Leave raw for webhook endpoint
  } else {
    try {
      const json = JSON.parse(body.toString());
      done(null, json);
    } catch (error) {
      error.statusCode = 400;
      done(error, undefined);
    }
  }
});

fastify.post('/webhooks/didit', async (request, reply) => {
  const signature = request.headers['x-signature'];
  const timestamp = request.headers['x-timestamp'];
  const rawBody = request.body;

  if (!signature || !timestamp || !rawBody) {
    reply.code(400).send({ message: 'Missing signature, timestamp, or body' });
    return;
  }

  // 1. Verify HMAC-SHA256 signature
  const expectedSignature = crypto
    .createHmac('sha256', DIDIT_WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody.toString()}`)
    .digest('hex');

  if (expectedSignature !== signature) {
    reply.code(403).send({ message: 'Invalid signature' });
    return;
  }

  // 2. Validate timestamp (e.g., within 5 minutes to prevent replay attacks)
  const fiveMinutesAgo = Date.now() - (5 * 60 * 1000);
  if (parseInt(timestamp) < fiveMinutesAgo) {
    reply.code(403).send({ message: 'Timestamp too old' });
    return;
  }

  // 3. Parse JSON body after verification
  let payload;
  try {
    payload = JSON.parse(rawBody.toString());
  } catch (error) {
    reply.code(400).send({ message: 'Invalid JSON payload' });
    return;
  }

  fastify.log.info('Received Didit webhook:', payload);

  // 4. Process the webhook payload (e.g., store in DB, update user status)
  try {
    await pgClient.query(
      'INSERT INTO webhooks (event_id, event_type, payload, received_at) VALUES ($1, $2, $3, NOW())',
      [payload.id, payload.event, JSON.stringify(payload)]
    );
    // Example: Update user status based on payload.status
    // await pgClient.query(
    //   'UPDATE users SET verification_status = $1 WHERE didit_session_id = $2',
    //   [payload.status, payload.session_id]
    // );
    reply.code(200).send({ message: 'Webhook received and processed' });
  } catch (dbError) {
    fastify.log.error('Database error:', dbError);
    reply.code(500).send({ message: 'Internal server error' });
  }
});

const start = async () => {
  try {
    await pgClient.connect();
    fastify.log.info('Connected to PostgreSQL');
    await fastify.listen({ port: 3000, host: '0.0.0.0' });
  } catch (err) {
    fastify.log.error(err);
    process.exit(1);
  }
};

start();

Хранение данных веб-хуков в PostgreSQL

Сохранение данных веб-хуков имеет решающее значение для аудита, отладки и обеспечения целостности данных. PostgreSQL — это надежная реляционная база данных, идеально подходящая для этой задачи.

1. Схема базы данных

Сначала создайте таблицу для хранения событий веб-хуков. Эта схема является хорошей отправной точкой:

CREATE TABLE webhooks (
    id SERIAL PRIMARY KEY,
    event_id VARCHAR(255) UNIQUE NOT NULL, -- Didit's unique event ID
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL, -- Store the full JSON payload
    received_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

2. Интеграция с Fastify

Как показано в примере app.js, мы интегрируем клиент pg для подключения к вашей базе данных PostgreSQL и вставки входящей полезной нагрузки веб-хука. Столбец payload JSONB NOT NULL идеально подходит для хранения всего объекта JSON, что позволяет в дальнейшем гибко выполнять запросы без предопределенных изменений схемы для каждого нового поля, которое Didit может ввести.

Не забудьте корректно обрабатывать потенциальные ошибки базы данных. Приведенный выше пример включает базовый блок try-catch для операций с базой данных.

Защита конечной точки веб-хука

Безопасность имеет первостепенное значение при работе с конфиденциальными данными проверки личности. Didit использует подписи HMAC-SHA256 для обеспечения легитимности и неизменности входящих веб-хуков.

1. Проверка подписи HMAC

Каждый запрос веб-хука Didit включает два важных заголовка: X-Signature и X-Timestamp. Заголовок X-Signature содержит подпись HMAC-SHA256, сгенерированную с использованием вашего уникального секрета веб-хука и необработанного тела запроса, объединенного с меткой времени. Ваш слушатель должен:

1. Получить ваш DIDIT_WEBHOOK_SECRET.
2. Извлечь заголовки X-Signature и X-Timestamp.
3. Восстановить подписанную полезную нагрузку: `${timestamp}.${rawBody}`.
4. Сгенерировать свою собственную подпись HMAC-SHA256, используя свой секрет и восстановленную полезную нагрузку.
5. Сравнить вашу сгенерированную подпись с X-Signature из запроса. Если они не совпадают, отклонить запрос.

Предоставленный пример Fastify демонстрирует этот точный процесс, гарантируя, что обрабатываются только аутентичные веб-хуки Didit.

2. Проверка метки времени

Заголовок X-Timestamp жизненно важен для предотвращения атак повторного воспроизведения. Атака повторного воспроизведения происходит, когда злоумышленник перехватывает легитимный веб-хук и отправляет его повторно позже. Проверяя, что метка времени является недавней (например, в течение 5 минут от текущего времени), вы можете снизить этот риск. Фрагмент кода Fastify включает проверку, чтобы убедиться, что метка времени не слишком старая.

Как помогает Didit

Платформа Didit разработана для того, чтобы сделать интеграцию проверки личности бесшовной и безопасной. Наша модульная архитектура позволяет вам подключать различные проверки личности, от проверки ID для надежного анализа документов до проверки NFC для высокозащищенных проверок электронных паспортов/удостоверений личности и скрининга и мониторинга AML для соблюдения требований. Система веб-хуков является основным компонентом этой модульности, предоставляя обновления в реальном времени, которые позволяют вам организовывать сложные рабочие процессы KYC без постоянного опроса.

Подход Didit, основанный на ИИ, означает, что наши системы постоянно учатся и адаптируются, обеспечивая превосходную точность и обнаружение мошенничества. Четкая документация API и ориентация на разработчиков, в сочетании с такими функциями, как бесплатный базовый KYC и отсутствие платы за настройку, облегчают начало работы. Наши веб-хуки предоставляют структурированные данные идентификации, позволяя вашему приложению интеллектуально реагировать на результаты проверки и автоматизировать доверие в масштабе, по всему миру. Независимо от того, нужно ли вам проверить возраст с помощью оценки возраста Didit или убедиться, что пользователь является живым человеком с помощью пассивной и активной проверки живости, Didit предоставляет инструменты и обратную связь в реальном времени, необходимые для надежного решения для идентификации.

Готовы начать?

Готовы увидеть Didit в действии? Получите бесплатную демонстрацию сегодня.

Начните бесплатно проверять личности с помощью бесплатного уровня Didit.