API ویب ہکس

جب عوامی API پر تخلیق یافتہ کام آخری حالت تک پہنچے اور آپ کے انضمام کو Rivya سے سرور پر اطلاع درکار ہو تو API ویب ہکس استعمال کریں۔

GET /api/v1/generations/{taskId} سے حالت بار بار جانچنے کی سہولت برقرار ہے۔ ویب ہکس عملی نظاموں کو دستخط شدہ واپسی اطلاع دیتے ہیں تاکہ واقعات براہِ راست پہنچ سکیں۔

درکار دائرۂ اختیار

ویب ہک کا نظم کرنے کے لیے اس دائرۂ اجازت والی API کلید درکار ہے:

webhooks:manage

ترتیبات میں بنائی گئی نئی کلیدوں میں یہ دائرۂ اجازت بطورِ طے شدہ شامل ہوتا ہے۔

اختتامی نقطہ بنائیں

POST /api/v1/webhooks

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

جواب میں signing_secret صرف ایک بار شامل ہوتا ہے:

{
  "id": "whend_...",
  "object": "webhook_endpoint",
  "name": "Production webhook",
  "url": "https://example.com/rivya/webhook",
  "event_types": ["generation.succeeded", "generation.failed"],
  "status": "active",
  "secret_preview": "whsec_12...abc123",
  "signing_secret": "whsec_...",
  "last_success_at": null,
  "last_failure_at": null,
  "failure_count": 0,
  "created_at": "2026-05-11T00:00:00.000Z",
  "updated_at": "2026-05-11T00:00:00.000Z",
  "disabled_at": null,
  "revoked_at": null
}

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

URL کے اصول

اختتامی نقطے کے URL کے لیے HTTPS لازم ہے۔ Rivya شناختی معلومات، ٹکڑوں، مقامی میزبان ناموں، مقامی نیٹ ورک کے پتوں اور غیر عوامی میزبانوں کو مسترد کرتا ہے۔

Rivya ہمیشہ یہ بھیجتا ہے:

• POST

• Content-Type: application/json

• صارف کے قابو والے کوئی اضافی درخواست سرنامے نہیں

• ازخود رخ بدلنے والے ربط کی پیروی نہیں

• حوالگی کے لیے مختصر مہلت

واقعات

موجودہ واقعات کی اقسام:

• generation.succeeded

• generation.failed

Webhook کا ابتدائی مواد حالت کے اختتامی نقطے والا ہی عوامی تخلیقی جوابی ڈھانچہ استعمال کرتا ہے۔

{
  "id": "evt_...",
  "type": "generation.succeeded",
  "api_version": "2026-05-11",
  "created_at": "2026-05-11T00:00:00.000Z",
  "data": {
    "generation": {
      "id": "task_public_id",
      "status": "succeeded",
      "model": "z-image",
      "reserved_credits": 1,
      "final_credits": 1,
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:01:00.000Z",
      "result": {
        "primary_url": "https://...",
        "urls": ["https://..."]
      },
      "error": null
    }
  }
}

ترسیلی ہیڈرز

ہر ترسیل میں یہ شامل ہوتا ہے:

Rivya-Webhook-Id: evt_...
Rivya-Webhook-Timestamp: 1778467200
Rivya-Webhook-Signature: v1=<hex-hmac-sha256>
Rivya-Webhook-Attempt: 1
Rivya-Webhook-Endpoint-Id: whend_...
Rivya-Request-Id: req_...

دستخط کا ابتدائی مواد:

${timestamp}.${rawBody}

طریقہ:

اختتامی نقطے کے دستخطی راز کے ساتھ HMAC-SHA256

پرانے وقتی نشانات والی درخواستیں مسترد کریں۔ پانچ منٹ کی گنجائش ایک عملی طے شدہ حد ہے۔

JavaScript میں تصدیق

import crypto from "node:crypto";

function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
  const timestamp = headers["rivya-webhook-timestamp"];
  const signature = headers["rivya-webhook-signature"] || "";
  const actual = signature.split(",").find((part) => part.startsWith("v1="))?.slice(3);
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!actual) return false;
  return crypto.timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
}

Python میں تصدیق

import hmac
import hashlib

def verify_rivya_webhook(raw_body: str, headers: dict, signing_secret: str) -> bool:
    timestamp = headers.get("rivya-webhook-timestamp", "")
    signature = headers.get("rivya-webhook-signature", "")
    actual = next((part[3:] for part in signature.split(",") if part.startswith("v1=")), "")
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return bool(actual) and hmac.compare_digest(actual, expected)

نقاطِ اتصال سنبھالیں

GET /api/v1/webhooks
GET /api/v1/webhooks/{endpointId}
PATCH /api/v1/webhooks/{endpointId}
DELETE /api/v1/webhooks/{endpointId}
POST /api/v1/webhooks/{endpointId}/rotate-secret

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..."

curl https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..."

curl -X PATCH https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../rotate-secret \
  -H "Authorization: Bearer rvya_sk_..."

DELETE /api/v1/webhooks/{endpointId} اختتامی نقطہ غیر فعال کرتا ہے۔ یہ حوالگی کی تاریخ حذف نہیں کرتا۔

ترسیل کے اندراجات

حالیہ واقعات کی فہرست دیکھیں:

GET /api/v1/webhook-events

curl https://rivya.ai/api/v1/webhook-events \
  -H "Authorization: Bearer rvya_sk_..."

کسی اختتامی نقطے کی حوالگی کی کوششوں کی فہرست دیکھیں:

GET /api/v1/webhooks/{endpointId}/deliveries

curl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
  -H "Authorization: Bearer rvya_sk_..."

حوالگی کے اندراجات میں حالت، HTTP حالت، کوشش کی تعداد، درخواست کی شناخت، دورانیہ، مختصر کیا گیا جوابی اقتباس اور عوامی خرابی کے خانے شامل ہوتے ہیں۔

آزمائشی واقعہ

محفوظ آزمائشی ابتدائی مواد بھیجیں:

POST /api/v1/webhooks/{endpointId}/test

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
  -H "Authorization: Bearer rvya_sk_..."

آزمائشی واقعہ webhook.test استعمال کرتا ہے۔ یہ تخلیقی کام نہیں بناتا، کریڈٹس استعمال نہیں کرتا اور حقیقی نتیجے کا URL شامل نہیں کرتا۔

دوبارہ کوشش کی پالیسی

Rivya HTTP 2xx کو کامیابی سمجھتا ہے۔

ناکامیوں میں نیٹ ورک خرابیاں، مہلت ختم ہونا، رخ بدلنے والے جوابات اور غیر 2xx جوابات شامل ہیں۔ Rivya پانچ کوششوں تک دوبارہ حوالگی کرتا ہے:

• فوراً

• 1 منٹ بعد

• 5 منٹ بعد

• 30 منٹ بعد

• 2 گھنٹے بعد

آخری کوشش کے بعد واقعے پر failed کی حالت لگا دی جاتی ہے۔

ویب ہک کی ترسیل میں ناکامی تخلیقی کام کی حیثیت، کریڈٹس، رقم کی واپسی یا کام کی تاریخ کو نہیں بدلتی۔

حفاظتی جانچ فہرست

• کاروباری منطق پڑھنے سے پہلے HMAC دستخط کی تصدیق کریں۔

• پرانے وقتی نشانات مسترد کریں۔

• آزمائشی واقعات کو تخلیقی کام کے واقعات سے الگ رکھیں۔

• دستخط کے مکمل راز اندراجات میں محفوظ نہ کریں۔

• 2xx صرف تب واپس بھیجیں جب آپ کا وصول کنندہ واقعہ قبول کر چکا ہو۔

• حساب ملانے کے لیے حالت بار بار جانچنے کو متبادل طریقے کے طور پر رکھیں۔

متعلقہ صفحات

• تخلیقی درخواست بھیجیں

• تخلیق کی حالت

• API خرابیاں اور حدود

• OpenAPI اور اسکیما کا معاہدہ