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 प्रमाण, फ्रैगमेंट, localhost नाम, स्थानीय नेटवर्क पते, निजी IP दायरे, लूपबैक पते और आरक्षित पते वाले URL अस्वीकार करता है।

Rivya हमेशा भेजता है:

• POST

• Content-Type: application/json

• उपयोगकर्ता द्वारा नियंत्रित कोई कस्टम अनुरोध हेडर नहीं

• अपने-आप पुनर्निर्देशन का अनुसरण नहीं

• वितरण के लिए छोटा समय-सीमा अंतराल

ईवेंट

मौजूदा घटना प्रकार:

• generation.succeeded

• generation.failed

वेबहुक का डेटा स्थिति समापन-बिंदु जैसा ही सार्वजनिक जनरेशन सीरियलाइज़र इस्तेमाल करता है।

{
  "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 स्थिति, प्रयास संख्या, अनुरोध ID, अवधि, जवाब का छोटा अंश और सार्वजनिक त्रुटि फ़ील्ड शामिल होते हैं।

परीक्षण ईवेंट

सुरक्षित परीक्षण डेटा भेजें:

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 और स्कीमा अनुबंध