Signed Rivya API webhook endpoints create کریں، delivery signatures verify کریں، delivery attempts inspect کریں، اور safe test events send کریں۔

جب آپ کی integration کو Public API generation کے terminal state تک پہنچنے کے بعد Rivya سے server notification چاہیے ہو تو API webhooks استعمال کریں۔

Polling GET /api/v1/generations/{taskId} اب بھی supported ہے۔ Webhooks production systems کے لیے signed callbacks add کرتے ہیں جو event delivery prefer کرتے ہیں۔

Required scope

Webhook management کے لیے اس scope والی API key چاہیے:

webhooks:manage

Settings میں created new keys default طور پر یہ scope include کرتی ہیں۔

Endpoint create کریں

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"]
  }'

Response میں 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
}

Full secret اپنے server پر store کریں۔ اگر یہ کھو جائے تو rotate endpoint call کریں اور اپنا receiver update کریں۔

URL rules

Endpoint URLs کو HTTPS ہونا چاہیے۔ Rivya credentials، fragments، localhost names، local network addresses، private IP ranges، loopback addresses، اور reserved addresses والی URLs reject کرتا ہے۔

Rivya ہمیشہ send کرتا ہے:

POST
Content-Type: application/json
کوئی custom user-controlled request headers نہیں
automatic redirect following نہیں
مختصر delivery timeout

Events

Current event types:

generation.succeeded
generation.failed

Webhook payloads status endpoint جیسا same public generation serializer استعمال کرتے ہیں۔

{
  "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
    }
  }
}

Delivery headers

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

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_...

Signature input:

${timestamp}.${rawBody}

Algorithm:

HMAC-SHA256 with the endpoint signing secret

Stale timestamps والی requests reject کریں۔ Five-minute tolerance practical default ہے۔

JavaScript verification

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 verification

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)

Endpoints manage کریں

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} endpoint کو disable کرتا ہے۔ یہ delivery history delete نہیں کرتا۔

Delivery records

Recent events list کریں:

GET /api/v1/webhook-events

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

کسی endpoint کے delivery attempts list کریں:

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

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

Delivery records میں status، HTTP status، attempt number، request id، duration، truncated response snippet، اور public error fields شامل ہوتے ہیں۔

Test event

Safe test payload send کریں:

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

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

Test event webhook.test استعمال کرتا ہے۔ یہ generation task create نہیں کرتا، credits consume نہیں کرتا، اور real result URL include نہیں کرتا۔

Retry policy

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

Failures میں network errors، timeout، redirect responses، اور non-2xx responses شامل ہیں۔ Rivya پانچ attempts تک retry کرتا ہے:

فوراً
1 minute بعد
5 minutes بعد
30 minutes بعد
2 hours بعد

Final attempt کے بعد event کو failed mark کیا جاتا ہے۔

Webhook delivery failures generation status، credits، refunds، یا task history کو change نہیں کرتے۔

Security checklist

Business logic parse کرنے سے پہلے HMAC signature verify کریں۔
Stale timestamps reject کریں۔
Test events کو generation events سے الگ treat کریں۔
Full signing secrets log نہ کریں۔
2xx صرف تب return کریں جب آپ کے receiver نے event accept کر لیا ہو۔
Reconciliation کے لیے polling کو fallback کے طور پر رکھیں۔

API webhooks

فہرست