API Webhooks
Set up Rivya API webhooks for generation events. Verify HMAC signatures, inspect delivery records, send test events, and handle retries.
Last reviewed on November 5, 2026
API webhooks send signed notifications to your server for Public API generation tasks. Register an endpoint, choose the events it receives, and verify each delivery before processing it.
You can also poll GET /api/v1/generations/{taskId} to check a task. Keep polling available to reconcile missed or delayed events.
Required Scope
Webhook management requires an active, unexpired Bearer API key with:
webhooks:manageNew keys created in Settings include this scope by default. Endpoints, events, and delivery records belong to the account, so a key with this scope can manage that account's endpoints even if another key created them.
The Public API and webhooks must both be enabled for these management routes. If the service is disabled, the API returns 503 with public_api_disabled.
Create Endpoint
POST /api/v1/webhookscurl 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"]
}'Replace the example key and URL before sending a request. This call registers an endpoint; it does not test delivery.
name is required and must contain 1–120 characters after trimming. url is required and must meet the URL rules. event_types is optional: omit it to subscribe to both generation events, or pass a nonempty array containing up to two supported event types.
A successful create request returns HTTP 201. The following response is illustrative; its IDs, secret, and timestamps are placeholders. The full signing_secret appears in the create response and in a secret-rotation response, but not in list, read, update, or disable responses.
{
"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
}Store the full secret on your server. If you lose it, rotate the secret and update your receiver. Rotation replaces the secret used for later deliveries; it does not provide a grace period for the old secret.
If a create or rotate request ends without a confirmed response, the operation may still have completed. Check the endpoint list before repeating a create request. An existing full secret cannot be retrieved; rotate it if you cannot recover the response.
URL Rules
Use an HTTPS URL for a publicly reachable receiver. The URL must be at most 2,048 characters and cannot contain credentials or a fragment. Do not use loopback, private-network, or reserved addresses.
The URL check rejects localhost names, names ending in .localhost or .local, and blocked literal IPv4 addresses. Registration does not resolve a hostname to check its destination.
Each delivery uses:
POSTContent-Type: application/jsonRivya's delivery headers, with no custom headers supplied by the endpoint owner
no automatic redirect following
a 10-second timeout
Events
Supported generation events:
generation.succeeded: the task has succeeded and itssettlement_statusisSETTLED.generation.failed: the task has failed. Checksettlement_statusandfinal_creditsto understand its credit outcome; this event alone does not confirm a refund.
Only Public API generation tasks produce these events. Studio tasks and chat responses do not. Events are queued only when the account has an active endpoint; delivery goes to active endpoints subscribed to that event type.
The event contains a snapshot of the public generation fields used by the status endpoint. A task that has succeeded but still needs credit reconciliation does not yet produce generation.succeeded.
This example shows a successful generation after credit settlement. The IDs, dates, and URLs are sample values; the credit amounts are examples rather than current model prices. api_version identifies the webhook payload version.
{
"id": "evt_...",
"type": "generation.succeeded",
"api_version": "2026-05-11",
"created_at": "2026-05-11T00:01:00.000Z",
"data": {
"generation": {
"id": "task_public_id",
"status": "succeeded",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "SETTLED",
"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
Each delivery includes these headers. The timestamp is Unix time in seconds; the values below are examples.
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 secretUse the timestamp header exactly as received, followed by a period and the unchanged request body. Read the body as UTF-8 text before parsing JSON. Do not rebuild it with JSON.stringify, reformat it, or normalize its characters before verification.
Reject timestamps more than five minutes in the past or future. The examples below use a 300-second tolerance and a constant-time digest comparison. Pass headers with lowercase names and string values.
JavaScript Verification
import crypto from "node:crypto";
function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
const timestamp = headers["rivya-webhook-timestamp"] || "";
const signature = headers["rivya-webhook-signature"] || "";
if (!/^[0-9]+$/.test(timestamp)) return false;
const timestampSeconds = Number(timestamp);
if (!Number.isSafeInteger(timestampSeconds)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds) > 300) {
return false;
}
const actual = signature
.split(",")
.map((part) => part.trim())
.find((part) => part.startsWith("v1="))
?.slice(3);
if (!actual || !/^[a-f0-9]{64}$/i.test(actual)) return false;
const expected = crypto
.createHmac("sha256", signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(actual, "hex"),
Buffer.from(expected, "hex")
);
}Python Verification
import hashlib
import hmac
import re
import time
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", "")
if not re.fullmatch(r"[0-9]+", timestamp):
return False
try:
timestamp_seconds = int(timestamp)
except ValueError:
return False
if abs(int(time.time()) - timestamp_seconds) > 300:
return False
parts = (part.strip() for part in signature.split(","))
actual = next((part[3:] for part in parts if part.startswith("v1=")), "")
if not re.fullmatch(r"[a-fA-F0-9]{64}", actual):
return False
expected = hmac.new(
signing_secret.encode("utf-8"),
f"{timestamp}.{raw_body}".encode("utf-8"),
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(actual.lower(), expected)After verification, parse the body and use the event id to detect repeats before applying business changes. A retry uses the same event ID, with a new timestamp, signature, and request ID. Timestamp checks do not replace duplicate detection.
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-secretcurl 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_..."PATCH can change name, url, event_types, or status. Provide at least one supported field. The status can be active or disabled; the same URL and event-type rules apply when updating an endpoint.
DELETE /api/v1/webhooks/{endpointId} disables the endpoint. It does not delete delivery history.
Missing, invalid, inactive, or expired API keys, and accounts that cannot use the Public API, receive 401. A key without the required scope receives 403. An endpoint outside the account, or an unknown endpoint ID, receives 404. Invalid input or a rejected URL receives 400. See API Errors and Limits for the error envelope.
Delivery Records
List recent generation events for the account:
GET /api/v1/webhook-eventscurl https://rivya.ai/api/v1/webhook-events \
-H "Authorization: Bearer rvya_sk_..."List delivery attempts for an endpoint:
GET /api/v1/webhooks/{endpointId}/deliveriescurl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
-H "Authorization: Bearer rvya_sk_..."Both routes return the newest records first. They default to 20 records and accept a positive limit up to 100. These responses do not include a pagination cursor.
Event records show status, attempts_count, and delivery or retry timestamps. Delivery records show status, http_status, attempt_number, request_id, duration_ms, a truncated response_snippet, and error_code and error_message.
Test Event
Send one test delivery to an active endpoint's registered URL:
POST /api/v1/webhooks/{endpointId}/testcurl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
-H "Authorization: Bearer rvya_sk_..."The test event uses webhook.test. It contains data.ping: true and the endpoint ID, with no generation task or real result URL. The test does not consume generation credits. It attempts a real signed HTTP delivery to your registered URL, so handle this event separately from generation events.
A completed test call returns HTTP 200 with the delivery result. Check its status: it can be success, failed, timeout, or skipped. The API's 200 does not mean that your receiver accepted the event.
The result is returned directly; test events and attempts are not added to the event or delivery lists. A test updates the endpoint's success or failure statistics and is not queued for automatic retries.
Retry Policy
Rivya treats a delivery as successful when it receives HTTP 2xx and finishes reading the response snippet. A network or response-read error, timeout, redirect, or other HTTP status can leave the delivery unsuccessful.
A generation event gets up to five delivery rounds. Endpoints with a recorded success are skipped in later rounds. The next round becomes eligible after the following delay from the end of the previous round:
first round: eligible when the event is queued
second round: after 1 minute
third round: after 5 minutes
fourth round: after 30 minutes
fifth round: after 2 hours
These are retry delays, not guaranteed delivery times. Queued events require Rivya's background delivery process to run. Actual delivery can be later if that process is delayed or unavailable.
An event is marked delivered when every currently active, subscribed endpoint has a recorded success. It is marked failed when retries are exhausted or no active endpoint subscribes to its event type. A failed event does not prove that every endpoint failed: another endpoint may already have accepted it.
Webhook delivery failures do not change generation status, credits, refunds, or task history.
Security Checklist
Verify the HMAC signature before processing the event.
Reject stale timestamps and detect repeated event IDs.
Treat test events separately from generation events.
Do not log full signing secrets.
Return
2xxonly after your receiver has accepted the event.Keep polling as a fallback for reconciliation.
