Webhook کے دستخط کی جانچ

ادائیگی کی اطلاع ایسے ایڈریس پر آتی ہے جو صرف آپ کا اسٹور اور ہماری سروس جانتے ہیں۔ لیکن ایڈریس لیک ہو سکتا ہے — لاگز سے، کنفیگریشن سے، ڈیولپمنٹ کی ہسٹری سے۔ اصل اطلاع کو جعلی سے الگ پہچاننے کے لیے ہر درخواست پر Webhook کی خفیہ کلید سے دستخط ہوتا ہے۔

آرڈر مکمل کرنے یا اس کا اسٹیٹس بدلنے سے پہلے دستخط جانچیں۔

دستخط کے ہیڈرز

ہیڈر	قدر
X-Timestamp	بھیجنے کا وقت، سیکنڈز میں unix time
X-Signature	sha256= سابقہ اور hex میں HMAC-SHA256

دستخط شدہ اسٹرنگ بھیجنے کا وقت، ایک نقطہ اور درخواست کی باڈی ہے:

1756901234.{"wallet":{...},"project":{...},"invoice":{...},"payment":{...}}

دستخط کی کلید پروجیکٹ کی سیٹنگز میں Webhook کی خفیہ کلید (Webhook secret) فیلڈ ہے۔ اگر قدر افشا ہو جائے، تو آپ اسے وہیں دوبارہ جاری کر سکتے ہیں۔

جانچ کے مراحل

1. JSON پارس کرنے سے پہلے درخواست کی خام باڈی لیں۔
2. X-Timestamp کی قدر، ایک نقطہ اور باڈی کو ملا کر ایک اسٹرنگ بنائیں۔
3. Webhook کی خفیہ کلید سے HMAC-SHA256 کا حساب لگائیں۔
4. نتیجے کا X-Signature سے موازنہ کریں، اور اس کے لیے constant-time موازنہ استعمال کریں۔
5. اگر X-Timestamp موجودہ وقت سے بہت زیادہ مختلف ہو، تو درخواست رد کر دیں۔

عمل درآمد کی مثالیں

PHP

<?php
$secret = 'webhook secret from your project settings';

$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Guards against a replayed request
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'sha256='.hash_hmac('sha256', $timestamp.'.'.$body, $secret);

// hash_equals compares in constant time
if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit;
}

$data = json_decode($body, true);

// Handle the order

http_response_code(200);

TypeScript

import { createHmac, timingSafeEqual } from 'node:crypto';
import express, { type Request, type Response } from 'express';

const app = express();
const secret = 'webhook secret from your project settings';

// The body must stay raw, so express.raw instead of express.json
app.post('/webhook', express.raw({ type: 'application/json' }), (req: Request, res: Response) => {
    const timestamp = req.get('X-Timestamp') ?? '';
    const signature = req.get('X-Signature') ?? '';
    const body = (req.body as Buffer).toString('utf8');

    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return res.sendStatus(400);
    }

    const expected = 'sha256=' + createHmac('sha256', secret)
        .update(`${timestamp}.${body}`, 'utf8')
        .digest('hex');

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);

    // Check the length first: timingSafeEqual needs buffers of equal size
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
        return res.sendStatus(403);
    }

    const data = JSON.parse(body);

    // Handle the order

    res.sendStatus(200);
});

JavaScript

وہی ہینڈلر ٹائپس کے بغیر — سادہ JavaScript پروجیکٹ کے لیے۔

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
const secret = 'webhook secret from your project settings';

// The body must stay raw, so express.raw instead of express.json
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const timestamp = req.get('X-Timestamp') ?? '';
    const signature = req.get('X-Signature') ?? '';
    const body = req.body.toString('utf8');

    if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
        return res.sendStatus(400);
    }

    const expected = 'sha256=' + createHmac('sha256', secret)
        .update(`${timestamp}.${body}`, 'utf8')
        .digest('hex');

    const a = Buffer.from(expected);
    const b = Buffer.from(signature);

    // Check the length first: timingSafeEqual needs buffers of equal size
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
        return res.sendStatus(403);
    }

    const data = JSON.parse(body);

    // Handle the order

    res.sendStatus(200);
});

Python

import hmac
import hashlib
import time

from flask import Flask, request

app = Flask(__name__)
secret = 'webhook secret from your project settings'


@app.post('/webhook')
def webhook():
    timestamp = request.headers.get('X-Timestamp', '')
    signature = request.headers.get('X-Signature', '')
    body = request.get_data(as_text=True)

    if abs(time.time() - int(timestamp or 0)) > 300:
        return '', 400

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        f'{timestamp}.{body}'.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return '', 403

    data = request.get_json()

    # Handle the order

    return '', 200

یاد رکھنے کی باتیں

دستخط خام باڈی پر ہوتا ہے۔ اگر آپ JSON پارس کر کے اسے دوبارہ بناتے ہیں، تو کلیدوں کی ترتیب اور خالی جگہیں بدل جاتی ہیں — دستخط مماثل نہیں رہتا۔ HMAC کا حساب پارس کرنے سے پہلے لگائیں۔

ہر دوبارہ کوشش کا اپنا دستخط ہوتا ہے۔ ہر دوبارہ کوشش پر بھیجنے کا وقت نیا ہوتا ہے، اس لیے دستخط بھی مختلف ہوتا ہے۔ آئندہ درخواستوں سے موازنے کے لیے دستخط محفوظ نہ کریں۔

خفیہ کلید دوبارہ جاری ہو سکتی ہے۔ دوبارہ جاری ہونے کے فوراً بعد پرانی خفیہ کلید کام کرنا بند کر دیتی ہے، اس لیے اسی وقت اپنے اسٹور میں قدر اپ ڈیٹ کریں۔

دستخط کی جانچ idempotency کا متبادل نہیں۔ دستخط ثابت کرتا ہے کہ درخواست اصلی ہے، یہ نہیں کہ آپ اسے پہلی بار دیکھ رہے ہیں۔ دوبارہ کوشش درست دستخط کے ساتھ آتی ہے — invoice.id سے جانچیں۔