Перейти к содержимому
Дашборд

Вебхуки и безопасность

DanDanPay Reseller API отправляет вебхуки на ваш сервер при наступлении ключевых событий жизненного цикла заказа.


Зарегистрируйте URL обработчика на вашем сервере для конкретного события:

Окно терминала
curl -X POST "https://api.dandanpay.net/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.myshop.com/webhooks/dandanpay",
"event": "order.status_updated"
}'
Событие Описание
order.status_updated Изменение статуса заказа (pending, processing, completed, error, failed)
order.credentials_requested Исполнитель запросил код подтверждения (OTP/2FA) или ссылку авторизации
order.receipt-requested Товар отгружен, ожидается подтверждение клиентом (confirm-receipt) или спор (dispute)
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "019818ab-0000-7c55-9477-5020aebf7000",
"event": "order.status_updated",
"url": "https://api.myshop.com/webhooks/dandanpay",
"secret": "whsec_019b4a2f8c7e9d1a3b5c7e9f...",
"is_active": true,
"created_at": "2026-09-13T10:00:00.000Z",
"updated_at": "2026-09-13T10:00:00.000Z"
}

Окно терминала
curl -X GET "https://api.dandanpay.net/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY"
Окно терминала
curl -X DELETE "https://api.dandanpay.net/v1/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_API_KEY"

Отправляет тестовое событие на зарегистрированный URL для проверки доступности:

Окно терминала
curl -X POST "https://api.dandanpay.net/v1/webhooks/123e4567-e89b-12d3-a456-426614174000/test" \
-H "Authorization: Bearer YOUR_API_KEY"

Каждый вебхук, отправляемый DanDanPay, содержит следующие HTTP-заголовки:

POST /webhooks/dandanpay HTTP/1.1
Host: api.myshop.com
Content-Type: application/json
X-Event-Type: order.status_updated
X-Event-Id: evt_019c8f00-0000-7000-8000-000000000001
X-Timestamp: 1788516000
X-Signature: sha256=4f2a7b8e9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f
X-Retry-Attempt: 0
  • X-Event-Type: имя события (order.status_updated, order.credentials_requested, order.receipt-requested).
  • X-Event-Id: уникальный идентификатор события. Обязателен для дедупликации на вашей стороне.
  • X-Timestamp: Unix-время отправки запроса в секундах. Защищает от атак повторного воспроизведения (Replay Attacks).
  • X-Signature: HMAC-SHA256 сигнатура в формате sha256=<hex_hash>.
  • X-Retry-Attempt: номер попытки (0 — первая доставка, 1+ — ретраи).

Алгоритм проверки:

  1. Возьмите сырые байты тела запроса (Raw Body) до парсинга в JSON.
  2. Сформируйте строку: ${X-Timestamp}.${RawBody}.
  3. Рассчитайте HMAC-SHA256 с вашим secret.
  4. Сравните результат с X-Signature через константное по времени сравнение (timingSafeEqual).
import crypto from 'crypto';
import express from 'express';
const app = express();
// ВАЖНО: сохраняем сырое тело запроса для проверки подписи
app.use(express.json({
verify: (req: any, _res, buf) => {
req.rawBody = buf;
}
}));
app.post('/webhooks/dandanpay', (req: any, res) => {
const secret = process.env.DANDANPAY_WEBHOOK_SECRET!;
const signature = req.headers['x-signature'] as string;
const timestamp = req.headers['x-timestamp'] as string;
const eventId = req.headers['x-event-id'] as string;
const eventType = req.headers['x-event-type'] as string;
if (!signature || !timestamp) {
return res.status(400).send('Missing signature headers');
}
// 1. Проверяем свежесть запроса (не старше 5 минут)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return res.status(400).send('Request timestamp expired');
}
// 2. Вычисляем HMAC-SHA256 подпись
const payloadToSign = `${timestamp}.${req.rawBody.toString('utf-8')}`;
const computedHash = crypto
.createHmac('sha256', secret)
.update(payloadToSign)
.digest('hex');
const expectedSignature = `sha256=${computedHash}`;
// 3. Безопасное сравнение
const isValid = crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// 4. Дедупликация по eventId
// if (await isEventAlreadyProcessed(eventId)) return res.status(200).send('OK');
console.log(`Получено событие ${eventType}:`, req.body);
// Всегда возвращайте HTTP 200 OK
return res.status(200).json({ success: true });
});

Тело запроса содержит объект OrderResponseDto:

{
"id": "019818bc-1285-7c55-9477-5020aebf7782",
"offer_id": "01981de8-7cb4-7f54-8672-57eb8ee8b47e",
"status": "completed",
"price": "1.0958",
"currency": "USD",
"reason": null,
"delivered_at": "2026-09-13T10:00:00.000Z",
"client_confirmed_at": "2026-09-13T10:02:00.000Z",
"disputed_at": null,
"auto_confirm_at": null
}

Запрос одноразового кода или ссылки входа:

{
"event_id": "evt_019c8f00-0000-7000-8000-000000000001",
"event": "order.credentials_requested",
"version": 1,
"created_at": "2026-09-13T10:05:00.000Z",
"data": {
"order_id": "019818bc-1285-7c55-9477-5020aebf7782",
"type": "otp",
"is_repeat": false,
"requested_at": "2026-09-13T10:05:00.000Z",
"expires_in": 300,
"expires_at": "2026-09-13T10:10:00.000Z"
}
}

Товар доставлен и ожидает подтверждения клиентом:

{
"event_id": "evt_019c8f00-0000-7000-8000-000000000002",
"event": "order.receipt-requested",
"version": 1,
"created_at": "2026-09-13T10:15:00.000Z",
"data": {
"order_id": "019818bc-1285-7c55-9477-5020aebf7782",
"delivered_at": "2026-09-13T10:15:00.000Z",
"auto_confirm_at": "2026-09-14T10:15:00.000Z",
"screenshots": [
"https://cdn.dandanpay.net/proofs/screenshot1.jpg"
]
}
}