signed Rivya API webhook endpoints create করুন, delivery signatures verify করুন, delivery attempts inspect করুন, এবং safe test events পাঠান।

Public API generation terminal state-এ পৌঁছানোর পরে Rivya যেন আপনার server-কে notify করে, এমন integration দরকার হলে API webhooks ব্যবহার করুন।

Polling GET /api/v1/generations/{taskId} এখনও supported। production systems event delivery পছন্দ করলে Webhooks signed callbacks যোগ করে।

Required Scope

Webhook management-এর জন্য API key-তে থাকতে হবে:

webhooks:manage

Settings-এ তৈরি নতুন keys defaultভাবে এই scope অন্তর্ভুক্ত করে।

Create Endpoint

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 শুধু একবার include করে:

{
  "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
no custom user-controlled request headers
no automatic redirect following
a 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 করুন। 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)

Manage Endpoints

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 হিসেবে treat করে।

Failures-এর মধ্যে network errors, timeout, redirect responses এবং non-2xx responses রয়েছে। Rivya up to five attempts retry করে:

immediately
after 1 minute
after 5 minutes
after 30 minutes
after 2 hours

final attempt-এর পরে event failed হিসেবে marked হয়।

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