Signed Rivya API webhook endpoints create करें, delivery signatures verify करें, delivery attempts inspect करें, और safe test events भेजें.

जब आपकी integration को Public API generation terminal state तक पहुंचने के बाद Rivya से server notification चाहिए, तब API webhooks इस्तेमाल करें।

Polling GET /api/v1/generations/{taskId} अभी भी supported है। Webhooks production systems के लिए signed callbacks जोड़ते हैं जो event delivery prefer करते हैं।

Required Scope

Webhook management के लिए इस scope वाली API key चाहिए:

webhooks:manage

Settings में created new keys में default रूप से यह scope शामिल होता है।

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 हमेशा भेजता है:

POST
Content-Type: application/json
कोई custom user-controlled request headers नहीं
कोई automatic redirect following नहीं
short delivery timeout

Events

Current event types:

generation.succeeded
generation.failed

Webhook payloads status endpoint जैसा ही 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 करें। Practical default के रूप में five-minute tolerance ठीक है।

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 भेजें:

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 शामिल नहीं करता।

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 नहीं बदलते।

Security Checklist

Business logic parse करने से पहले HMAC signature verify करें।
Stale timestamps reject करें।
Test events को generation events से अलग treat करें।
Full signing secrets log न करें।
अपना receiver event accept कर लेने के बाद ही 2xx return करें।
Reconciliation के fallback के रूप में polling रखें।

API Webhooks