Skip to content
Dashboard

Webhooks & Security

The DanDanPay Reseller API dispatches webhooks to your server upon key state transitions in the order lifecycle.


Register an endpoint URL on your server for a specific event type:

Terminal window
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"
}'
Event Description
order.status_updated Order status updated (pending, processing, completed, error, failed)
order.credentials_requested Supplier requested 2FA code (OTP/2FA) or device authorization link
order.receipt-requested Goods delivered, awaiting customer confirmation (confirm-receipt) or dispute (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"
}

Terminal window
curl -X GET "https://api.dandanpay.net/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY"
Terminal window
curl -X DELETE "https://api.dandanpay.net/v1/webhooks/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_API_KEY"

Send Test Webhook: POST /v1/webhooks/{id}/test

Section titled “Send Test Webhook: POST /v1/webhooks/{id}/test”

Sends a synthetic test event to your registered URL to verify reachability and signature computation:

Terminal window
curl -X POST "https://api.dandanpay.net/v1/webhooks/123e4567-e89b-12d3-a456-426614174000/test" \
-H "Authorization: Bearer YOUR_API_KEY"

Every webhook dispatched by DanDanPay contains the following HTTP headers:

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: Event name (order.status_updated, order.credentials_requested, order.receipt-requested).
  • X-Event-Id: Unique event ID. Crucial for idempotency & deduplication on your server.
  • X-Timestamp: Unix timestamp in seconds when the request was dispatched. Prevents replay attacks.
  • X-Signature: HMAC-SHA256 signature in sha256=<hex_hash> format.
  • X-Retry-Attempt: Delivery attempt count (0 is initial attempt, 1+ are retries).

Verification algorithm:

  1. Capture the raw unparsed request body bytes before any JSON parsing.
  2. Build the signing string: ${X-Timestamp}.${RawBody}.
  3. Compute the HMAC-SHA256 hash using your webhook secret.
  4. Compare your computed signature against X-Signature using a constant-time comparison (timingSafeEqual).
import crypto from 'crypto';
import express from 'express';
const app = express();
// IMPORTANT: Preserve raw request body bytes for signature calculation
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. Verify request timestamp freshness (prevent replay attacks, max 5 min)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return res.status(400).send('Request timestamp expired');
}
// 2. Compute expected HMAC-SHA256 signature
const payloadToSign = `${timestamp}.${req.rawBody.toString('utf-8')}`;
const computedHash = crypto
.createHmac('sha256', secret)
.update(payloadToSign)
.digest('hex');
const expectedSignature = `sha256=${computedHash}`;
// 3. Constant-time comparison
const isValid = crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
// 4. Deduplicate event using eventId
// if (await isEventAlreadyProcessed(eventId)) return res.status(200).send('OK');
console.log(`Received event ${eventType}:`, req.body);
// Always return HTTP 200 OK
return res.status(200).json({ success: true });
});

The payload contains an OrderResponseDto object:

{
"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
}

Provider request for OTP/2FA or login authorization:

{
"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"
}
}

Goods delivered and awaiting buyer confirmation:

{
"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"
]
}
}