Partner API Reference

hwy_at_<64 lowercase hex characters>

Example: hwy_at_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

GET /api/partner/v1/verifications HTTP/1.1
Host: huwiyya.syria-cloud.sy
Authorization: Bearer hwy_at_a1b2c3d4e5f6...your-token...
Content-Type: application/json

# Obtain access token using client certificate
curl -X POST https://huwiyya.syria-cloud.sy/api/partner/v1/oauth/token \
  --cert client.pem --key client-key.pem \
  -d "grant_type=client_credentials&client_id=hwy_a1b2c3d4..."

# Use the access token with mTLS
curl -X GET https://huwiyya.syria-cloud.sy/api/partner/v1/verifications \
  --cert client.pem --key client-key.pem \
  -H "Authorization: Bearer hwy_at_..." \
  -H "Content-Type: application/json"

{
  "client": {
    "id": "c1d2e3f4-a5b6-7890-c1d2-e3f4a5b67890",
    "clientId": "hwy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "clientName": "Production mTLS Client",
    "certificateThumbprint": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9",
    "certificateSubjectDN": "CN=partner.example.com, O=Partner Corp",
    "certificateNotBefore": "2026-01-01T00:00:00+00:00",
    "certificateNotAfter": "2027-01-01T00:00:00+00:00",
    "allowedScopes": "verifications webhooks evidence reports",
    "isActive": true,
    "createdAt": "2026-03-23T14:00:00+00:00"
  },
  "clientId": "hwy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

curl -X POST https://huwiyya.syria-cloud.sy/api/partner/v1/oauth/token \
  --cert client.pem --key client-key.pem \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=hwy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

{
  "access_token": "hwy_at_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "verifications webhooks evidence reports",
  "cnf": {
    "x5t#S256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
  }
}

curl -X GET https://huwiyya.syria-cloud.sy/api/partner/v1/verifications \
  --cert client.pem --key client-key.pem \
  -H "Authorization: Bearer hwy_at_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

{
  "active": true,
  "client_id": "hwy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "scope": "verifications webhooks evidence reports",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "exp": 1711209600,
  "iat": 1711206000,
  "token_type": "Bearer",
  "cnf": {
    "x5t#S256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
  }
}

{
  "active": false
}

[
  {
    "id": "c1d2e3f4-a5b6-7890-c1d2-e3f4a5b67890",
    "clientId": "hwy_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "clientName": "Production mTLS Client",
    "certificateThumbprint": "b94d27b993...efcde9",
    "certificateSubjectDN": "CN=partner.example.com",
    "certificateNotAfter": "2027-01-01T00:00:00+00:00",
    "isActive": true,
    "createdAt": "2026-01-10T09:00:00+00:00",
    "lastUsedAt": "2026-03-23T13:45:00+00:00",
    "revokedAt": null
  }
]

{
  "documentType": "SyrianNationalId",
  "externalReference": "user-abc-123"
}

{
  "caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionToken": "stok_Kj8mNqP3rL9vWxYzA1bCdE2fGhIjKl",
  "status": "SessionIssued",
  "expiresAt": "2026-03-23T16:00:00+00:00"
}

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalReference": "user-abc-123",
  "status": "Approved",
  "documentType": "SyrianNationalId",
  "compositeRiskScore": 0.12,
  "decisionReason": "All automated checks passed.",
  "createdAt":   "2026-03-23T14:00:00+00:00",
  "updatedAt":   "2026-03-23T14:08:31+00:00",
  "completedAt": "2026-03-23T14:08:31+00:00",
  "session": {
    "id": "a2b3c4d5-e6f7-...",
    "expiresAt": "2026-03-23T16:00:00+00:00",
    "isUsed": true,
    "usedAt": "2026-03-23T14:02:10+00:00"
  },
  "documentEvidence": [
    {
      "id": "e1f2a3b4-...",
      "evidenceType": "DocumentFront",
      "contentType": "image/jpeg",
      "fileSizeBytes": 524288,
      "originalFileName": "front.jpg",
      "sha256Hash": "a1b2c3d4e5f6...",
      "uploadedAt": "2026-03-23T14:03:50+00:00"
    }
  ],
  "selfieEvidence": [ "..." ],
  "videoEvidence":  [ "..." ],
  "ocrResult": {
    "modelName": "huwiyya-ocr",
    "modelVersion": "1.0.0",
    "confidenceScore": 0.96,
    "extractedFieldsJson": "{"fullName":"Ahmad Al-Souri","idNumber":"12345678"}",
    "mrzIsValid": null,
    "mrzRawText": null,
    "hasManipulationIndicators": false,
    "inferenceTimestamp": "2026-03-23T14:06:10+00:00",
    "inferenceLatencyMs": 834
  },
  "faceMatch": {
    "modelName": "huwiyya-facematch",
    "modelVersion": "1.0.0",
    "similarityScore": 0.94,
    "threshold": 0.85,
    "isMatch": true,
    "inferenceTimestamp": "2026-03-23T14:06:11+00:00",
    "inferenceLatencyMs": 421
  },
  "liveness": {
    "modelName": "huwiyya-liveness",
    "modelVersion": "1.0.0",
    "livenessScore": 0.98,
    "threshold": 0.75,
    "isLive": true,
    "presentationAttackDetected": false,
    "attackType": null,
    "inferenceTimestamp": "2026-03-23T14:06:13+00:00",
    "inferenceLatencyMs": 612
  },
  "fraudSignals": [],
  "reviewDecisions": []
}

{
  "items": [
    {
      "id": "3fa85f64-...",
      "externalReference": "user-abc-123",
      "status": "Approved",
      "documentType": "SyrianNationalId",
      "compositeRiskScore": 0.12,
      "createdAt":   "2026-03-23T14:00:00+00:00",
      "completedAt": "2026-03-23T14:08:31+00:00"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 147,
  "totalPages": 3
}

{
  "reason": "User withdrew consent."
}

{
  "fields": {
    "fullName": "أحمد السوري",
    "idNumber": "12345678"
  },
  "notes": "Corrected name transliteration from OCR output."
}

{
  "modelName": "huwiyya-ocr",
  "modelVersion": "1.0.0",
  "confidenceScore": 0.96,
  "extractedFieldsJson": "{\"fullName\":\"أحمد السوري\",\"idNumber\":\"12345678\"}",
  "mrzIsValid": null,
  "mrzRawText": null,
  "hasManipulationIndicators": false,
  "inferenceTimestamp": "2026-03-23T14:06:10+00:00",
  "inferenceLatencyMs": 834
}

[
  {
    "id": "b1c2d3e4-5678-4abc-d9ef-012345678901",
    "url": "https://yourbank.com/events/huwiyya",
    "eventTypes": ["verification.approved", "verification.rejected"],
    "isActive": true,
    "createdAt": "2026-01-15T10:00:00+00:00"
  }
]

{
  "url": "https://yourbank.com/events/huwiyya",
  "eventTypes": [
    "verification.approved",
    "verification.rejected",
    "verification.failed",
    "verification.pending_manual_review"
  ]
}

{
  "endpoint": {
    "id": "b1c2d3e4-5678-4abc-d9ef-012345678901",
    "url": "https://yourbank.com/events/huwiyya",
    "eventTypes": ["verification.approved", "verification.rejected"],
    "isActive": true,
    "createdAt": "2026-03-23T14:00:00+00:00"
  },
  "signingSecret": "whsec_Kj8mNqP3rL9vWxYzA1bCdE2fGhIjKlMnOpQrStUvWxYz"
}

{
  "url": "https://yourbank.com/events/huwiyya-v2",
  "eventTypes": ["verification.approved", "verification.failed"]
}

{
  "newSigningSecret": "whsec_NewRotatedSecretReturnedOnce..."
}

{
  "deliveries": [
    {
      "id": "d1e2f3a4-...",
      "eventType": "verification.approved",
      "caseId": "3fa85f64-...",
      "httpStatus": 200,
      "attemptCount": 1,
      "lastAttemptAt": "2026-03-23T14:09:00+00:00",
      "succeeded": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1
}

{
  "from": "2026-02-23T00:00:00+00:00",
  "to":   "2026-03-23T23:59:59+00:00",
  "totalCases": 847,
  "byStatus": {
    "Approved":           612,
    "Rejected":            91,
    "PendingManualReview": 23,
    "Failed":               8,
    "Expired":            113
  },
  "automationRate": 0.93
}

CaseId,Status,DocumentType,ExternalReference,CreatedAt,CompletedAt,CompositeRiskScore,DecisionReason

{
  "eventType":  "verification.approved",
  "eventId":    "evt_3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp":  "2026-03-23T14:09:00+00:00",
  "apiVersion": "v1",
  "tenantId":   "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "data": {
    "caseId":            "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "externalReference": "user-abc-123",
    "status":            "Approved",
    "documentType":      "SyrianNationalId",
    "compositeRiskScore": 0.12,
    "decisionReason":    "All automated checks passed.",
    "completedAt":       "2026-03-23T14:08:31+00:00"
  }
}

const crypto = require('crypto');

function verifyHuwiyyaSignature(req, signingSecret) {
  const signature = req.headers['x-huwiyya-signature']; // "sha256=abc123..."
  const timestamp  = req.headers['x-huwiyya-timestamp']; // Unix epoch seconds

  if (!signature || !timestamp) return false;

  // Reject replays older than 5 minutes
  const ageSeconds = Math.abs(Date.now() / 1000 - parseInt(timestamp, 10));
  if (ageSeconds > 300) return false;

  // req.rawBody must be the raw Buffer — do NOT parse before verifying
  const computed = 'sha256=' + crypto
    .createHmac('sha256', signingSecret)
    .update(timestamp + '.' + req.rawBody)
    .digest('hex');

  // Constant-time comparison prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(computed, 'utf8'),
    Buffer.from(signature, 'utf8'),
  );
}

// Express route — use express.raw() to preserve the raw body
app.post(
  '/events/huwiyya',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    if (!verifyHuwiyyaSignature(req, process.env.HUWIYYA_WEBHOOK_SECRET)) {
      return res.status(401).send('Invalid signature');
    }
    const event = JSON.parse(req.body);
    // Handle event.eventType, event.data ...
    res.sendStatus(200);
  },
);

import hashlib, hmac, time

def verify_huwiyya_signature(
    headers: dict,
    raw_body: bytes,
    signing_secret: str,
) -> bool:
    signature = headers.get('X-Huwiyya-Signature', '')  # "sha256=abc123..."
    timestamp  = headers.get('X-Huwiyya-Timestamp', '')

    if not signature or not timestamp:
        return False

    # Reject replays older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False

    payload = timestamp.encode() + b'.' + raw_body
    expected = 'sha256=' + hmac.new(
        signing_secret.encode(),
        payload,
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison to prevent timing attacks
    return hmac.compare_digest(expected, signature)

{
  "type":   "https://tools.ietf.org/html/rfc7807",
  "title":  "Conflict",
  "status": 409,
  "detail": "A verification case with this idempotency key already exists.",
  "code":   "CASE_EXISTS"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/problem+json

{
  "title":  "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after the indicated interval.",
  "code":   "RATE_LIMITED"
}

POST /api/partner/v1/verifications HTTP/1.1
Authorization: Bearer hwy_at_a1b2c3d4e5f6...your-token...
Idempotency-Key: 7f9c8a1b-3d2e-4f5a-b6c7-d8e9f0a1b2c3
Content-Type: application/json

{
  "documentType": "SyrianNationalId",
  "externalReference": "user-abc-123"
}