Webhooks

Λήψη ειδοποιήσεων κατάστασης πληρωμής σε πραγματικό χρόνο

Τα webhooks επιτρέπουν στην Cost+ να ειδοποιεί τον διακομιστή σας σε πραγματικό χρόνο κάθε φορά που αλλάζει η κατάσταση μιας παραγγελίας. Αντί να κάνετε polling στο API, παρέχετε ένα URL και η Cost+ στέλνει ένα αίτημα HTTP POST σε αυτό κάθε φορά που υπάρχει ενημέρωση.

Πώς Λειτουργούν τα Webhooks

Καθορίζετε ένα webhook_url κατά τη δημιουργία μιας παραγγελίας, ή ρυθμίζετε ένα προεπιλεγμένο URL webhook σε επίπεδο project.
Όταν αλλάζει η κατάσταση παραγγελίας (π.χ., από new σε completed), η Cost+ στέλνει ένα αίτημα POST στο URL webhook σας.
Ο διακομιστής σας λαμβάνει το webhook, και στη συνέχεια καλεί το API της Cost+ για να ανακτήσει τα πλήρη στοιχεία παραγγελίας.
Ενημερώνετε το σύστημά σας βάσει της επαληθευμένης κατάστασης παραγγελίας.

Μην εμπιστεύεστε ποτέ μόνο το payload του webhook για να εκτελέσετε μια παραγγελία. Πάντα επαληθεύετε την κατάσταση παραγγελίας κάνοντας ένα αίτημα GET /v1/orders/{id}/ μετά τη λήψη ενός webhook. Το webhook είναι μηχανισμός ειδοποίησης, όχι πηγή αλήθειας.

Payload Webhook

Το σώμα του webhook είναι ένα αντικείμενο JSON που περιέχει τον τύπο συμβάντος και το αναγνωριστικό παραγγελίας:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Πεδίο	Περιγραφή
`event`	Ο τύπος συμβάντος. Αυτή τη στιγμή `status_changed` για ενημερώσεις παραγγελιών.
`order_id`	Το μοναδικό αναγνωριστικό της παραγγελίας της οποίας η κατάσταση άλλαξε.
`project_id`	Το project στο οποίο ανήκει η παραγγελία.

Ρύθμιση URL Webhook

Μπορείτε να ορίσετε το URL webhook με δύο τρόπους:

Ανά Παραγγελία

Συμπεριλάβετε το πεδίο webhook_url κατά τη δημιουργία μιας παραγγελίας:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Προεπιλογή Project

Ρυθμίστε ένα προεπιλεγμένο URL webhook στον πίνακα ελέγχου Cost+ στις ρυθμίσεις project. Αυτό το URL θα χρησιμοποιείται για όλες τις παραγγελίες που δεν καθορίζουν το δικό τους webhook_url.

Ακόμα και αν έχετε μια προεπιλογή σε επίπεδο project, μπορείτε να την αντικαταστήσετε ανά παραγγελία συμπεριλαμβάνοντας webhook_url στο αίτημα δημιουργίας παραγγελίας.

Λογική Επαναπροσπαθειών

Αν ο διακομιστής σας δεν απαντήσει με κωδικό κατάστασης 2xx, η Cost+ επαναπροσπαθεί την παράδοση webhook:

Μέγιστες επαναπροσπάθειες: 10 προσπάθειες
Διάστημα επαναπροσπαθειών: 2 λεπτά μεταξύ κάθε προσπάθειας
Χρονικό όριο πρώτης προσπάθειας: 4 δευτερόλεπτα
Χρονικό όριο επόμενων προσπαθειών: 10 δευτερόλεπτα

Αν αποτύχουν και οι 10 προσπάθειες, το webhook σημειώνεται ως αποτυχημένο. Μπορείτε ακόμα να ανακτήσετε την κατάσταση παραγγελίας ανά πάσα στιγμή κάνοντας polling στο API.

Βεβαιωθείτε ότι το endpoint webhook σας απαντά γρήγορα (εντός 4 δευτερολέπτων για την πρώτη προσπάθεια). Εκτελέστε οποιαδήποτε χρονοβόρα επεξεργασία ασύγχρονα μετά την επιστροφή μιας απόκρισης 200 OK.

Βέλτιστες Πρακτικές

Πάντα επαληθεύετε μέσω API. Μόλις λάβετε ένα webhook, καλέστε GET /v1/orders/\{order_id\}/ για να επιβεβαιώσετε την τρέχουσα κατάσταση πριν προβείτε σε ενέργειες όπως αποστολή αγαθών ή παροχή πρόσβασης.
Επιστρέψτε 200 γρήγορα. Αναγνωρίστε το webhook με μια απόκριση 200 αμέσως και επεξεργαστείτε την παραγγελία ασύγχρονα για να αποφύγετε τα χρονικά όρια.
Χειριστείτε τα διπλότυπα. Το endpoint webhook σας μπορεί να λάβει το ίδιο συμβάν περισσότερες από μία φορές. Βεβαιωθείτε ότι η λογική επεξεργασίας σας είναι idempotent.
Χρησιμοποιήστε HTTPS. Πάντα χρησιμοποιήστε HTTPS URL για το endpoint webhook σας για να διασφαλίσετε ότι το payload μεταδίδεται με ασφάλεια.
Καταγράψτε τα payloads webhook. Αποθηκεύστε τα εισερχόμενα δεδομένα webhook για εντοπισμό σφαλμάτων και σκοπούς ελέγχου.

Σχετικά Endpoints

Δημιουργία Παραγγελίας — ορισμός webhook_url ανά παραγγελία
Ενημέρωση Παραγγελίας — ενημέρωση του URL webhook σε υπάρχουσα παραγγελία
Σχήματα Συμβάντων Webhook — μορφή payload για OrderStatusChangedEvent και TransactionStatusChangedEvent

On this page