API & Webhooks Reference

API model

Πώς χρησιμοποιείται το API

Το Nutrition Hub χρησιμοποιεί ελεγχόμενη server-to-server επικοινωνία για license validation, plan features, private updates, billing events, OAuth flows, AI requests και άλλα integrations.

Doctor site

Installation client

Η WordPress εγκατάσταση στέλνει signed requests με installation context, timestamp και request ID.

Central platform

Validation service

Επαληθεύει άδεια, domain, plan, features, signature και επιτρεπτή ενέργεια.

External provider

Webhook sender

Google, payment provider ή άλλη υπηρεσία στέλνει event στο κατάλληλο callback endpoint.

Queue worker

Asynchronous processing

Βαριές ή επαναλαμβανόμενες εργασίες εκτελούνται σε queue με retries και idempotency.

Το δημόσιο reference δεν πρέπει να αποκαλύπτει εσωτερικά secrets.

Τα examples χρησιμοποιούν placeholders και ενδεικτικά fields. Η τελική production τεκμηρίωση πρέπει να συμφωνεί ακριβώς με τον κώδικα της έκδοσης.

Environments

Production και staging

Environment	Χρήση	Credentials	Δεδομένα
Production	Πραγματικοί λογαριασμοί και ενεργές integrations.	Ξεχωριστά production secrets.	Μόνο τα αναγκαία πραγματικά δεδομένα.
Staging	Testing releases, callbacks και migrations.	Διαφορετικά test/staging credentials.	Test ή ανωνυμοποιημένα δεδομένα.
Local development	Unit, integration και local E2E tests.	Local-only secrets.	Συνθετικά δεδομένα.

Μη χρησιμοποιείτε production secrets σε staging.

Η απομόνωση environments περιορίζει τον κίνδυνο accidental billing, πραγματικών emails ή ανεπιθύμητων production events.

Authentication

Μορφές αυθεντικοποίησης

Installation API

Signed installation request

Χρησιμοποιεί installation ή license identity μαζί με HMAC signature και timestamp.

User context

WordPress session / nonce

Για browser-to-WordPress actions χρησιμοποιείται authenticated user session, capability check και nonce όπου απαιτείται.

OAuth

Provider authorization

Google και παρόμοιες υπηρεσίες χρησιμοποιούν OAuth access και refresh tokens που προστατεύονται server-side.

Provider webhook

Provider signature

Payment ή άλλος provider υπογράφει το raw webhook payload με δικό του signing secret ή verification mechanism.

Authentication δεν σημαίνει authorization.

Μετά την ταυτοποίηση, κάθε endpoint πρέπει να ελέγχει plan, feature, tenant, role και resource ownership.

Request signing

HMAC υπογραφή και replay protection

Η παρακάτω δομή είναι ενδεικτική. Τα ακριβή headers και η canonical string πρέπει να επιβεβαιωθούν από τον production κώδικα.

Ενδεικτικά request headers

Content-Type: application/json
X-NH-Installation: inst_example_123
X-NH-Timestamp: 1783681200
X-NH-Request-ID: req_01JEXAMPLE
X-NH-Signature: sha256=EXAMPLE_SIGNATURE

Ενδεικτική canonical string

POST
/v1/license/validate
1783681200
req_01JEXAMPLE
SHA256_HEX(raw_request_body)

Ενδεικτικός υπολογισμός

signature = HMAC_SHA256(
  canonical_string,
  installation_secret
)

Έλεγχοι που πρέπει να εφαρμόζονται

Σύγκριση signature με constant-time function.
Απόρριψη timestamp εκτός του επιτρεπτού tolerance window.
Έλεγχος installation identity και ενεργής άδειας.
Απόρριψη duplicate request ID όπου απαιτείται.
Υπογραφή του raw body πριν από JSON normalization.
Καταγραφή request ID και status χωρίς το secret.

Μην υπογράφετε μόνο επιλεγμένα client fields.

Η υπογραφή πρέπει να καλύπτει το canonical request ή hash του raw body ώστε να αποτρέπεται η αλλοίωση payload.

Request format

JSON requests και validation

Ενδεικτικό request payload

{
  "event": "license.validate",
  "installation_id": "inst_example_123",
  "site_url": "https://clinic.example/",
  "plugin_version": "1.0.0",
  "request_id": "req_01JEXAMPLE",
  "sent_at": "2026-07-10T10:00:00Z"
}

Input validation

Έλεγχος	Παράδειγμα
Required fields	Απόρριψη όταν λείπει event ή request ID.
Type validation	Το timestamp είναι αριθμός ή valid ISO datetime.
Allowlist	Μόνο επιτρεπτά event names και fields.
Length limits	Περιορισμός strings, arrays και request body.
URL validation	HTTPS και εγκεκριμένο domain όπου απαιτείται.
Business validation	Feature διαθέσιμο στο συγκεκριμένο plan.

Αγνοήστε ή απορρίψτε άγνωστα fields με συνεπή πολιτική.

Για security-sensitive endpoints προτείνεται αυστηρό schema και απόρριψη μη αναμενόμενων fields.

Response format

Συνεπείς αποκρίσεις

Επιτυχής απόκριση

{
  "ok": true,
  "request_id": "req_01JEXAMPLE",
  "data": {
    "status": "active",
    "plan": "professional",
    "features": ["calendar", "files", "email"]
  }
}

Απόκριση σφάλματος

{
  "ok": false,
  "request_id": "req_01JEXAMPLE",
  "error": {
    "code": "NH_INVALID_SIGNATURE",
    "message": "Request authentication failed."
  }
}

HTTP status	Χρήση	Retry;
`200`	Επιτυχής ανάγνωση ή idempotent processing.	Όχι
`201`	Δημιουργήθηκε resource.	Όχι
`202`	Έγινε αποδοχή για asynchronous processing.	Όχι άμεσα
`400`	Invalid payload ή validation error.	Όχι χωρίς διόρθωση
`401`	Missing ή invalid authentication.	Όχι χωρίς νέα credentials
`403`	Authenticated αλλά μη εξουσιοδοτημένο request.	Όχι
`404`	Resource ή route δεν βρέθηκε.	Συνήθως όχι
`409`	Conflict ή duplicate state.	Ανά περίπτωση
`422`	Valid JSON αλλά μη αποδεκτή business validation.	Όχι χωρίς αλλαγή
`429`	Rate limit exceeded.	Ναι, μετά από backoff
`500`	Μη αναμενόμενο server error.	Ναι, περιορισμένα
`503`	Προσωρινά μη διαθέσιμη υπηρεσία.	Ναι

Μην επιστρέφετε stack traces ή secrets.

Η δημόσια απόκριση περιέχει σταθερό error code, ασφαλές μήνυμα και request ID. Οι λεπτομέρειες παραμένουν σε προστατευμένο log.

Idempotency

Αποφυγή διπλής επεξεργασίας

Idempotency σημαίνει ότι η επανάληψη του ίδιου request δεν δημιουργεί δεύτερη χρέωση, δεύτερο email, δεύτερο appointment event ή άλλη μη αναστρέψιμη ενέργεια.

Payments

Transaction event ID

Κάθε provider event αποθηκεύεται μία φορά πριν αλλάξει το billing status.

Message idempotency key

Η ίδια appointment notification δεν δημιουργείται ξανά από duplicated trigger.

Calendar

Appointment-to-event mapping

Το ίδιο appointment ενημερώνει το υπάρχον Google event αντί να δημιουργεί νέο.

License

Request ID

Επαναλαμβανόμενο signed request μπορεί να επιστρέφει το προηγούμενο ασφαλές αποτέλεσμα.

Ενδεικτικό idempotency header

Idempotency-Key: appt_4821_confirmation_v1

Το key συνδέεται με συγκεκριμένο operation scope.
Αποθηκεύεται status και αποτέλεσμα της πρώτης επεξεργασίας.
Το ίδιο key με διαφορετικό payload απορρίπτεται.
Υπάρχει καθορισμένο retention για idempotency records.

Webhook processing

Ασφαλής λήψη και επεξεργασία webhooks

Λήψη raw request body

Μην τροποποιείτε το payload πριν από signature verification.

Επαλήθευση signature

Χρησιμοποιήστε το επίσημο provider mechanism και το σωστό signing secret.

Έλεγχος timestamp

Απορρίψτε events εκτός του επιτρεπτού replay window.

Έλεγχος event ID

Αν το event έχει ήδη επεξεργαστεί, επιστρέψτε ασφαλές idempotent response.

Validation και account mapping

Επιβεβαιώστε event type, amount, currency, tenant και subscription/customer reference.

Γρήγορο acknowledgement

Επιστρέψτε επιτυχία γρήγορα και μεταφέρετε βαριά εργασία σε queue όπου είναι κατάλληλο.

Καταγραφή αποτελέσματος

Αποθηκεύστε event ID, status, timestamps και safe metadata χωρίς secret ή πλήρη ευαίσθητα payloads.

Ενδεικτικό webhook payload

{
  "id": "evt_example_123",
  "type": "subscription.payment_succeeded",
  "created_at": "2026-07-10T10:00:00Z",
  "data": {
    "account_ref": "acct_example",
    "subscription_ref": "sub_example",
    "amount": 4900,
    "currency": "EUR",
    "status": "paid"
  }
}

Μην εμπιστεύεστε το payload πριν επαληθευτεί.

Amount, status, tenant και resource references θεωρούνται untrusted μέχρι να ολοκληρωθεί signature και business validation.

Retries and queues

Retry policy

Τα retries χρησιμοποιούνται μόνο για προσωρινές αποτυχίες. Validation, authentication και permission errors δεν πρέπει να επαναλαμβάνονται αδιάκοπα.

Αποτυχία	Retry;	Προτεινόμενη συμπεριφορά
Network timeout	Ναι	Exponential backoff και jitter.
HTTP 429	Ναι	Σεβασμός Retry-After όταν παρέχεται.
HTTP 500 / 503	Ναι	Περιορισμένες επαναλήψεις με backoff.
HTTP 400 / 422	Όχι	Διόρθωση payload ή business state.
HTTP 401 / 403	Όχι αυτόματα	Credential refresh ή manual investigation.
Duplicate event	Όχι	Idempotent success response.

Ενδεικτικό backoff

Attempt 1: 1 minute
Attempt 2: 5 minutes
Attempt 3: 15 minutes
Attempt 4: 1 hour
Final: manual review / dead-letter queue

Το retry schedule είναι ενδεικτικό.

Η τελική δημόσια τιμή πρέπει να συμφωνεί με το πραγματικό queue implementation και τις απαιτήσεις του provider.

Rate limits

Περιορισμός χρήσης και abuse protection

Per installation

Installation quota

Περιορίζει υπερβολικά requests από μία εγκατάσταση ή license.

Per route

Endpoint-specific limits

Per IP

Network abuse control

Συμπληρωματικός έλεγχος χωρίς να αντικαθιστά user ή tenant authentication.

Per plan

Usage quotas

AI requests, tokens ή άλλες metered λειτουργίες ελέγχονται σύμφωνα με το ενεργό πλάνο.

Ενδεικτικά response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1783681260
Retry-After: 30

Versioning and compatibility

API versioning

Το major API version εμφανίζεται στο path ή στο contract.
Backward-compatible fields μπορούν να προστεθούν χωρίς breaking change.
Αφαίρεση ή αλλαγή σημασίας field απαιτεί νέα major έκδοση.
Deprecated endpoints έχουν σαφή περίοδο μετάβασης.
Το plugin δηλώνει την API έκδοση που υποστηρίζει.
Τα changelog entries περιγράφουν required actions.

Μην βασίζεστε στη σειρά JSON fields.

Οι clients πρέπει να διαβάζουν named fields και να χειρίζονται επιτρεπτά πρόσθετα fields σύμφωνα με το contract.

Logging

Privacy-safe τεχνικά logs

Καταγράφεται	Δεν καταγράφεται
Request ID, route, status, latency	API secrets ή Authorization headers
Installation ή tenant-safe reference	Πλήρη OAuth tokens
Error code και retry count	Πλήρη payment card data
Provider event ID	Μη αναγκαίο patient content
Payload hash όπου χρειάζεται	Raw sensitive payload χωρίς λόγο

Support diagnostics

Τι στέλνουμε για API πρόβλημα

Στείλτε

Environment: production ή staging.
Route ή integration name.
Request ID και event ID.
HTTP status και Nutrition Hub error code.
Timestamp με timezone.
Plugin version και πρόσφατες αλλαγές.

Μην στείλετε

API key ή signing secret.
Authorization header.
OAuth access/refresh token.
Πλήρες raw patient payload.

FAQ

Συχνές ερωτήσεις

Γιατί χρειάζεται request ID;

Επιτρέπει ασφαλή συσχέτιση client και server logs χωρίς να απαιτείται ανταλλαγή ολόκληρου payload.

Τι διαφορά έχει το request ID από το idempotency key;

Το request ID αναγνωρίζει ένα τεχνικό request. Το idempotency key αναγνωρίζει μία business operation που δεν πρέπει να εκτελεστεί δεύτερη φορά.

Γιατί επαληθεύουμε το raw webhook body;

Επειδή ο provider υπολογίζει τη signature πάνω στην ακριβή ακολουθία bytes. Η επανακωδικοποίηση JSON μπορεί να αλλάξει το περιεχόμενο και να ακυρώσει ή να αποδυναμώσει τον έλεγχο.

Πρέπει να επιστρέψουμε 200 σε duplicate webhook;

Συνήθως ναι, όταν το event έχει ήδη επεξεργαστεί σωστά. Έτσι ο provider δεν συνεχίζει άσκοπα retries.

Μπορεί το frontend να κρατά API secret;

Όχι. Οτιδήποτε αποστέλλεται στον browser θεωρείται δημόσια προσβάσιμο. Τα secrets παραμένουν server-side.