↓
Τεκμηρίωση Rivya AI

Webhooks του API

Δημιουργήστε υπογεγραμμένα endpoints webhook του Rivya API, επαληθεύστε υπογραφές παράδοσης, ελέγξτε προσπάθειες παράδοσης και στείλτε ασφαλή δοκιμαστικά συμβάντα.

Τελευταίος έλεγχος στις 2026/05/11

Χρησιμοποιήστε webhooks του API όταν η ενσωμάτωσή σας χρειάζεται το Rivya να ειδοποιεί τον διακομιστή σας μόλις μια δημιουργία του Δημόσιου API φτάσει σε τελική κατάσταση.

Ο περιοδικός έλεγχος με GET /api/v1/generations/{taskId} εξακολουθεί να υποστηρίζεται. Τα webhooks προσθέτουν υπογεγραμμένες επανακλήσεις για συστήματα παραγωγής που προτιμούν παράδοση συμβάντων.

Απαιτούμενο scope

Η διαχείριση webhooks απαιτεί API key με:

webhooks:manage

Τα νέα κλειδιά που δημιουργούνται στις Ρυθμίσεις περιλαμβάνουν αυτό το πεδίο πρόσβασης από προεπιλογή.

Δημιουργία endpoint webhook

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
}

Αποθηκεύστε ολόκληρο το μυστικό στον διακομιστή σας. Αν το χάσετε, καλέστε το endpoint ανανέωσης και ενημερώστε το σύστημα λήψης.

Κανόνες URL

Τα URL των endpoints πρέπει να χρησιμοποιούν HTTPS. Το Rivya απορρίπτει URL με διαπιστευτήρια, τμήματα κατακερματισμού, ονόματα localhost, διευθύνσεις τοπικού δικτύου, ιδιωτικά εύρη IP, διευθύνσεις loopback και δεσμευμένες διευθύνσεις.

Το Rivya στέλνει πάντα:

  • POST

  • Content-Type: application/json

  • χωρίς προσαρμοσμένες κεφαλίδες αιτήματος που ελέγχει ο χρήστης

  • χωρίς αυτόματη ακολούθηση ανακατευθύνσεων

  • με σύντομο χρονικό όριο παράδοσης

Συμβάντα

Τρέχοντες τύποι συμβάντων:

  • generation.succeeded

  • generation.failed

Τα ωφέλιμα φορτία webhook χρησιμοποιούν τον ίδιο δημόσιο μηχανισμό σειριοποίησης δημιουργιών με το endpoint κατάστασης.

{
  "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 με το μυστικό υπογραφής του endpoint

Απορρίψτε αιτήματα με παλιές χρονικές σημάνσεις. Μια ανοχή πέντε λεπτών είναι πρακτική προεπιλογή.

Επαλήθευση 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)

Διαχείριση endpoints webhook

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. Δεν διαγράφει το ιστορικό παραδόσεων.

Εγγραφές παραδόσεων

Λίστα πρόσφατων συμβάντων:

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

Λίστα προσπαθειών παράδοσης για ένα endpoint:

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

Οι εγγραφές παράδοσης περιλαμβάνουν κατάσταση, κατάσταση HTTP, αριθμό προσπάθειας, αναγνωριστικό αιτήματος, διάρκεια, περικομμένο απόσπασμα απόκρισης και δημόσια πεδία σφάλματος.

Δοκιμαστικό συμβάν

Στείλτε ένα ασφαλές δοκιμαστικό ωφέλιμο φορτίο:

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.

Οι αποτυχίες παράδοσης webhook δεν αλλάζουν την κατάσταση δημιουργίας, τις μονάδες, τις επιστροφές ή το ιστορικό εργασιών.

Λίστα ελέγχου ασφαλείας

  • Επαληθεύστε την υπογραφή HMAC πριν εφαρμόσετε την επιχειρησιακή λογική.

  • Απορρίψτε παλιές χρονικές σημάνσεις.

  • Αντιμετωπίστε τα δοκιμαστικά συμβάντα ξεχωριστά από τα συμβάντα δημιουργίας.

  • Μην καταγράφετε ολόκληρα μυστικά υπογραφής.

  • Επιστρέψτε 2xx μόνο αφού το σύστημα λήψης έχει αποδεχτεί το συμβάν.

  • Διατηρήστε τον περιοδικό έλεγχο ως εναλλακτική για συμφωνία κατάστασης.

Σχετικές σελίδες

Files API

Ανεβάστε αρχεία αναφοράς εικόνας, βίντεο ή ήχου για αιτήματα generation του Rivya API, με ελέγχους MIME, όρια μεγέθους και duration tokens.

Αρχείο αλλαγών API

Παρακολουθήστε ενημερώσεις τεκμηρίωσης, endpoint, αναφοράς μοντέλων, schema και μελλοντικών επιφανειών του Rivya API v1.

Πίνακας περιεχομένων

Απαιτούμενο scope
Δημιουργία endpoint webhook
Κανόνες URL
Συμβάντα
Κεφαλίδες παράδοσης
Επαλήθευση JavaScript
Επαλήθευση Python
Διαχείριση endpoints webhook
Εγγραφές παραδόσεων
Δοκιμαστικό συμβάν
Πολιτική επανάληψης
Λίστα ελέγχου ασφαλείας
Σχετικές σελίδες