# التحقق من التوقيعات

تأكد من أن عملية التسليم صادرة عن AdProMaxPay ولم تُعدَّل ولم يُعَد إرسالها، بعشر لغات.

يستطيع أي شخص إرسال طلب إلى عنوان الـ webhook لديك. قبل أن تثق بعملية تسليم، تحقّق من توقيعها:
فهو يثبت أن AdProMaxPay أرسل هذا النص بعينه، حديثًا، بسرّ نقطة الاستقبال لديك.

## ترويسة التوقيع

تحمل كل عملية تسليم ترويسة `X-AdProMaxPay-Signature`:

* `t` وقت التوقيع، بثواني Unix؛
* `v1` قيمة HMAC-SHA256، بالنظام الست عشري، للنص `t` + `.` + نص الطلب الخام، بمفتاح هو
  سرّ توقيع نقطة الاستقبال لديك (`apx_whsec_…`، يُستخدم كاملًا كمفتاح).

أثناء تجديد السرّ، تحمل الترويسة قيمتين لـ `v1`، واحدة لكل سرّ. تكون عملية التسليم أصلية
عندما تتطابق **أي** قيمة `v1`.

```text
X-AdProMaxPay-Signature: t=1790851200,v1=d2e39688034d…9a9879e
```

## تحقّق من عملية تسليم

1. اقرأ **نص الطلب الخام**، تمامًا كما وصل، قبل أي تحليل لـ JSON. النص الذي يُحلَّل ثم يُعاد
   تسلسله لا يطابق توقيعه بعد ذلك.
2. قسّم الترويسة عند `,`، ثم كل جزء عند أول `=`: احتفظ بـ `t` وبكل `v1`.
3. ارفض عملية التسليم التي يبتعد `t` فيها عن ساعتك بأكثر من **خمس دقائق**: قد تكون عملية تسليم
   قديمة أُعيد إرسالها.
4. احسب HMAC-SHA256 للنص `t` + `.` + نص الطلب الخام بسرّك، بالنظام الست عشري.
5. قارنه بكل `v1` في **زمن ثابت**. إذا تطابقت قيمة واحدة، فعملية التسليم أصلية.

أجب بـ `400` على عملية التسليم التي تفشل، ولا تفعل بها شيئًا. تنفّذ الدوال هنا الخطوات الخمس؛
وكل منها مُختبرة على المثال الموقّع نفسه.

```bash title="verify-signature.sh"
# Usage: verify_signature <file holding the raw body> "<header>" "<secret>"
# A check by hand; your server should verify in its own language.
# NOW replaces the clock, for tests.
verify_signature() {
  local body_file="$1" header="$2" secret="$3"
  local now="${NOW:-$(date +%s)}" timestamp expected
  timestamp=$(printf '%s\n' "$header" | tr ',' '\n' \
    | sed -n 's/^ *t=//p' | head -n 1)
  case "$timestamp" in '' | *[!0-9]*) return 1 ;; esac
  [ $((now - timestamp)) -le 300 ] || return 1
  [ $((timestamp - now)) -le 300 ] || return 1
  expected=$({ printf '%s.' "$timestamp"; cat "$body_file"; } \
    | openssl dgst -sha256 -hmac "$secret" | sed 's/^.*= //')
  printf '%s\n' "$header" | tr ',' '\n' | sed 's/^ *//' \
    | grep -qx "v1=$expected"
}
```

```js title="verify-signature.mjs"
import { Buffer } from 'node:buffer'
import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

// True when `header` (X-AdProMaxPay-Signature) signs `rawBody`
// (a Buffer or a string) with `secret` and is under five minutes old.
export function verifySignature(rawBody, header, secret, now) {
  let timestamp = null
  const signatures = []
  for (const part of String(header).split(',')) {
    const [key, value] = part.trim().split('=', 2)
    if (key === 't')
      timestamp = value
    else if (key === 'v1' && value !== undefined)
      signatures.push(value)
  }
  if (timestamp === null || !/^\d+$/.test(timestamp))
    return false
  const clock = now ?? Math.floor(Date.now() / 1000)
  if (Math.abs(clock - Number(timestamp)) > TOLERANCE_SECONDS)
    return false
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest()
  return signatures.some((signature) => {
    const given = Buffer.from(signature, 'hex')
    return given.length === expected.length
      && timingSafeEqual(given, expected)
  })
}
```

```ts title="verify-signature.ts"
import { Buffer } from 'node:buffer'
import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 300

// True when `header` (X-AdProMaxPay-Signature) signs `rawBody`
// with `secret` and is under five minutes old.
export function verifySignature(
  rawBody: Buffer | string,
  header: string,
  secret: string,
  now: number = Math.floor(Date.now() / 1000),
): boolean {
  let timestamp: string | null = null
  const signatures: string[] = []
  for (const part of header.split(',')) {
    const [key, value] = part.trim().split('=', 2)
    if (key === 't' && value !== undefined)
      timestamp = value
    else if (key === 'v1' && value !== undefined)
      signatures.push(value)
  }
  if (timestamp === null || !/^\d+$/.test(timestamp))
    return false
  if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS)
    return false
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest()
  return signatures.some((signature) => {
    const given = Buffer.from(signature, 'hex')
    return given.length === expected.length
      && timingSafeEqual(given, expected)
  })
}
```

```python title="verify_signature.py"
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300

def verify_signature(raw_body, header, secret, now=None):
    """True when header (X-AdProMaxPay-Signature) signs raw_body
    (bytes) with secret and is under five minutes old."""
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)
    if not (timestamp and timestamp.isascii() and timestamp.isdigit()):
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256)
    digest = expected.hexdigest().encode()
    return any(hmac.compare_digest(digest, s.encode()) for s in signatures)
```

```php title="verify_signature.php"
<?php
const TOLERANCE_SECONDS = 300;

// True when $header (X-AdProMaxPay-Signature) signs $rawBody
// with $secret and is under five minutes old.
function verify_signature(
    string $rawBody,
    string $header,
    string $secret,
    ?int $now = null
): bool {
    $timestamp = null;
    $signatures = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);
        if ($pair[0] === 't' && isset($pair[1])) {
            $timestamp = $pair[1];
        } elseif ($pair[0] === 'v1' && isset($pair[1])) {
            $signatures[] = $pair[1];
        }
    }
    if ($timestamp === null || !ctype_digit($timestamp)) {
        return false;
    }
    if (abs(($now ?? time()) - (int) $timestamp) > TOLERANCE_SECONDS) {
        return false;
    }
    $signed = $timestamp . '.' . $rawBody;
    $expected = hash_hmac('sha256', $signed, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }
    return false;
}
```

```ruby title="verify_signature.rb"
require 'openssl'

TOLERANCE_SECONDS = 300

# True when header (X-AdProMaxPay-Signature) signs raw_body
# with secret and is under five minutes old. Ruby 3.0 or later.
def verify_signature(raw_body, header, secret, now = Time.now.to_i)
  timestamp = nil
  signatures = []
  header.split(',').each do |part|
    key, value = part.strip.split('=', 2)
    timestamp = value if key == 't'
    signatures << value if key == 'v1' && value
  end
  return false unless timestamp&.match?(/\A\d+\z/)
  return false if (now - timestamp.to_i).abs > TOLERANCE_SECONDS

  signed = "#{timestamp}.".b + raw_body.b
  expected = OpenSSL::HMAC.hexdigest('SHA256', secret, signed)
  signatures.any? do |signature|
    OpenSSL.secure_compare(expected, signature)
  end
end
```

```go title="signature.go"
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

const toleranceSeconds = 300

// VerifySignature reports whether header (X-AdProMaxPay-Signature)
// signs rawBody with secret and is under five minutes old.
func VerifySignature(rawBody []byte, header, secret string, now time.Time) bool {
	var timestamp string
	var signatures []string
	for _, part := range strings.Split(header, ",") {
		key, value, found := strings.Cut(strings.TrimSpace(part), "=")
		switch {
		case found && key == "t":
			timestamp = value
		case found && key == "v1":
			signatures = append(signatures, value)
		}
	}
	if timestamp == "" || strings.Trim(timestamp, "0123456789") != "" {
		return false
	}
	signedAt, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	age := now.Unix() - signedAt
	if age > toleranceSeconds || age < -toleranceSeconds {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := mac.Sum(nil)
	for _, signature := range signatures {
		given, err := hex.DecodeString(signature)
		if err == nil && hmac.Equal(given, expected) {
			return true
		}
	}
	return false
}
```

```java title="WebhookSignature.java"
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.HexFormat;
import java.util.List;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class WebhookSignature {
    private static final long TOLERANCE_SECONDS = 300;

    // True when header (X-AdProMaxPay-Signature) signs rawBody
    // with secret and is under five minutes old. Java 17 or later.
    public static boolean verify(byte[] rawBody, String header, String secret, long now)
            throws GeneralSecurityException {
        String timestamp = null;
        List<String> signatures = new ArrayList<>();
        for (String part : header.split(",")) {
            String[] pair = part.trim().split("=", 2);
            if (pair.length < 2) {
                continue;
            }
            if (pair[0].equals("t")) {
                timestamp = pair[1];
            } else if (pair[0].equals("v1")) {
                signatures.add(pair[1]);
            }
        }
        if (timestamp == null || !timestamp.matches("\\d{1,18}")) {
            return false;
        }
        if (Math.abs(now - Long.parseLong(timestamp)) > TOLERANCE_SECONDS) {
            return false;
        }
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.UTF_8));
        byte[] expected = mac.doFinal(rawBody);
        for (String signature : signatures) {
            try {
                byte[] given = HexFormat.of().parseHex(signature);
                if (MessageDigest.isEqual(expected, given)) {
                    return true;
                }
            } catch (IllegalArgumentException notHexadecimal) {
                // Not one of our signatures.
            }
        }
        return false;
    }

    public static boolean verify(byte[] rawBody, String header, String secret)
            throws GeneralSecurityException {
        return verify(rawBody, header, secret, System.currentTimeMillis() / 1000);
    }
}
```

```csharp title="WebhookSignature.cs"
using System.Globalization;
using System.Security.Cryptography;
using System.Text;

public static class WebhookSignature
{
    private const long ToleranceSeconds = 300;

    // True when header (X-AdProMaxPay-Signature) signs rawBody
    // with secret and is under five minutes old.
    public static bool Verify(byte[] rawBody, string header, string secret, long? now = null)
    {
        string? timestamp = null;
        var signatures = new List<string>();
        foreach (var part in header.Split(','))
        {
            var pair = part.Trim().Split('=', 2);
            if (pair.Length < 2) continue;
            if (pair[0] == "t") timestamp = pair[1];
            else if (pair[0] == "v1") signatures.Add(pair[1]);
        }
        if (!long.TryParse(timestamp, NumberStyles.None, CultureInfo.InvariantCulture, out var signedAt))
            return false;
        var clock = now ?? DateTimeOffset.UtcNow.ToUnixTimeSeconds();
        if (Math.Abs(clock - signedAt) > ToleranceSeconds)
            return false;

        var signed = Encoding.UTF8.GetBytes(timestamp + ".").Concat(rawBody).ToArray();
        var expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), signed);
        foreach (var signature in signatures)
        {
            try
            {
                var given = Convert.FromHexString(signature);
                if (CryptographicOperations.FixedTimeEquals(expected, given))
                    return true;
            }
            catch (FormatException)
            {
                // Not one of our signatures.
            }
        }
        return false;
    }
}
```

```rust title="signature.rs"
// Cargo.toml: hmac = "0.12", sha2 = "0.10", hex = "0.4"
use hmac::{Hmac, Mac};
use sha2::Sha256;

const TOLERANCE_SECONDS: i64 = 300;

/// True when `header` (X-AdProMaxPay-Signature) signs `raw_body` with
/// `secret` and is under five minutes old. `now` is in Unix seconds.
pub fn verify_signature(raw_body: &[u8], header: &str, secret: &str, now: i64) -> bool {
    let mut timestamp = None;
    let mut signatures = Vec::new();
    for part in header.split(',') {
        match part.trim().split_once('=') {
            Some(("t", value)) => timestamp = Some(value),
            Some(("v1", value)) => signatures.push(value),
            _ => {}
        }
    }
    let Some(timestamp) = timestamp else {
        return false;
    };
    if timestamp.is_empty() || !timestamp.bytes().all(|byte| byte.is_ascii_digit()) {
        return false;
    }
    let Ok(signed_at) = timestamp.parse::<i64>() else {
        return false;
    };
    if (now - signed_at).abs() > TOLERANCE_SECONDS {
        return false;
    }
    signatures.iter().any(|signature| {
        let Ok(given) = hex::decode(signature) else {
            return false;
        };
        let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes())
            .expect("HMAC takes a key of any length");
        mac.update(timestamp.as_bytes());
        mac.update(b".");
        mac.update(raw_body);
        // Compares in constant time.
        mac.verify_slice(&given).is_ok()
    })
}
```

## اقرأ نص الطلب الخام

تحلّل معظم أطر العمل JSON قبل أن يعمل كودك. اطلب البايتات الخام بدل ذلك، في مسار
الـ webhook فقط.

* **Node**: مع Express، ركّب `express.raw({ type: 'application/json' })` على المسار؛ فيصبح `req.body`
  من النوع `Buffer`. ومع `node:http`، اجمع أجزاء الطلب، كما في
  [البدء السريع للبطاقة](https://pay-docs.adpromax.com/ar/get-started/quickstart-card#6-عالج-الحدث).
* **PHP**: اقرأ `php://input`. وفي Laravel، `$request->getContent()`.
* **Python**: في Flask، `request.get_data()`؛ وفي Django، `request.body`.
* **Ruby**: في Rails، `request.raw_post`؛ وفي Sinatra، `request.body.read`.
* **Go**: `io.ReadAll(r.Body)`.
* **Java**: في Spring، معامل من النوع `@RequestBody byte[]`.
* **C#**: انسخ `Request.Body` إلى `MemoryStream` قبل أي ربط للنموذج (model binding).
* **Rust**: في axum، المستخرج `Bytes`.

```bash
# From a terminal, send the bytes exactly as they are: --data-binary.
# -d would strip the line breaks, and the signature would not match.
curl -i http://localhost:4242/webhooks/payments \
  -H "Content-Type: application/json" \
  -H "X-AdProMaxPay-Signature: t=$T,v1=$SIG" \
  --data-binary @event.json
```

```js title="express.mjs"
app.post('/webhooks/payments',
  express.raw({ type: 'application/json' }), (req, res) => {
    const header = req.get('X-AdProMaxPay-Signature') ?? ''
    const secret = process.env.APX_WEBHOOK_SECRET
    if (!verifySignature(req.body, header, secret))
      return res.sendStatus(400)
    const event = JSON.parse(req.body.toString('utf8'))
    res.sendStatus(200)
    handle(event) // your own code, after answering
  })
```

```ts title="express.ts"
app.post('/webhooks/payments',
  express.raw({ type: 'application/json' }),
  (req: Request, res: Response) => {
    const rawBody = req.body as Buffer
    const header = req.get('X-AdProMaxPay-Signature') ?? ''
    const secret = process.env.APX_WEBHOOK_SECRET ?? ''
    if (!verifySignature(rawBody, header, secret))
      return res.sendStatus(400)
    const event = JSON.parse(rawBody.toString('utf8')) as WebhookEvent
    res.sendStatus(200)
    handle(event) // your own code, after answering
  })
```

```python title="views.py"
@csrf_exempt
@require_POST
def webhook(request):
    header = request.headers.get("X-AdProMaxPay-Signature", "")
    secret = os.environ["APX_WEBHOOK_SECRET"]
    if not verify_signature(request.body, header, secret):
        return HttpResponse(status=400)
    event = json.loads(request.body)
    # Your own code, quickly: answer within 10 seconds.
    return HttpResponse(status=200)
```

```php title="web.php"
Route::post('/webhooks/payments', function (Request $request) {
    $valid = verify_signature(
        $request->getContent(),
        $request->header('X-AdProMaxPay-Signature', ''),
        getenv('APX_WEBHOOK_SECRET'),
    );
    abort_unless($valid, 400);
    $event = json_decode($request->getContent(), true);
    // Your own code, quickly: answer within 10 seconds.
    return response()->noContent();
});
```

```ruby title="webhooks_controller.rb"
class WebhooksController < ApplicationController
  skip_forgery_protection

  def create
    valid = verify_signature(
      request.raw_post,
      request.headers['X-AdProMaxPay-Signature'].to_s,
      ENV.fetch('APX_WEBHOOK_SECRET')
    )
    return head :bad_request unless valid

    event = JSON.parse(request.raw_post)
    # Your own code, quickly: answer within 10 seconds.
    head :ok
  end
end
```

```go title="handler.go"
func webhook(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	header := r.Header.Get("X-AdProMaxPay-Signature")
	secret := os.Getenv("APX_WEBHOOK_SECRET")
	if !VerifySignature(rawBody, header, secret, time.Now()) {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	// Your own code, quickly: answer within 10 seconds.
	w.WriteHeader(http.StatusOK)
}
```

```java title="WebhookController.java"
@RestController
public class WebhookController {
    @PostMapping("/webhooks/payments")
    public ResponseEntity<Void> receive(
            @RequestBody byte[] rawBody,
            @RequestHeader("X-AdProMaxPay-Signature") String header)
            throws GeneralSecurityException {
        String secret = System.getenv("APX_WEBHOOK_SECRET");
        if (!WebhookSignature.verify(rawBody, header, secret)) {
            return ResponseEntity.badRequest().build();
        }
        // Your own code, quickly: answer within 10 seconds.
        return ResponseEntity.ok().build();
    }
}
```

```csharp title="Program.cs"
app.MapPost("/webhooks/payments", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var valid = WebhookSignature.Verify(
        buffer.ToArray(),
        request.Headers["X-AdProMaxPay-Signature"].ToString(),
        Environment.GetEnvironmentVariable("APX_WEBHOOK_SECRET")!);
    if (!valid)
        return Results.BadRequest();
    // Your own code, quickly: answer within 10 seconds.
    return Results.Ok();
});
```

```rust title="handler.rs"
// axum: `Bytes` is the body exactly as it was received.
async fn webhook(headers: HeaderMap, body: Bytes) -> StatusCode {
    let header = headers
        .get("x-adpromaxpay-signature")
        .and_then(|value| value.to_str().ok())
        .unwrap_or("");
    let secret = std::env::var("APX_WEBHOOK_SECRET").unwrap_or_default();
    if !verify_signature(&body, header, &secret, unix_now()) {
        return StatusCode::BAD_REQUEST;
    }
    // Your own code, quickly: answer within 10 seconds.
    StatusCode::OK
}
```

## عند تجديد السرّ

جدّد سرّ نقطة الاستقبال من لوحة التحكم إذا احتُمل تسرّبه، أو على سبيل العادة. تختار المدة
التي يظل فيها السرّ القديم يوقّع: لا شيء، أو ساعة واحدة، أو يومًا. وخلالها تحمل كل عملية تسليم
قيمتين لـ `v1`، ليقبلها إعدادك القديم والجديد معًا. ثبّت السرّ الجديد
قبل انتهاء فترة التداخل.

## اختبر معالجك

وقّع نصًا بنفسك وأرسله إلى معالجك: الرد `2xx` يعني أن تحققك يقبل عملية تسليم
سليمة. غيّر حرفًا واحدًا في النص وأرسله من جديد: يجب أن يجيب معالجك بـ `400`.

```bash title="Terminal"
SECRET="$APX_WEBHOOK_SECRET"
BODY='{"id":"evt_handler_test","object":"event",
"type":"payment_intent.succeeded","data":{"object":{}}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.*= //')

curl -i http://localhost:4242/webhooks/payments \
  -H "Content-Type: application/json" \
  -H "X-AdProMaxPay-Signature: t=$T,v1=$SIG" \
  --data-binary "$BODY"
```