8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
9.1 KiB
Plaintext
87 lines
9.1 KiB
Plaintext
---
|
|
title: Webhooks
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Ανακαλύψτε πώς να χρησιμοποιείτε τα Webhooks μας.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## Επισκόπηση
|
|
|
|
Τα Webhooks στο Twenty συμπληρώνουν το API ενεργοποιώντας **ενημερώσεις σε πραγματικό χρόνο** στις εφαρμογές σας όταν συμβαίνουν ορισμένα γεγονότα στο CRM σας. Αντί να αναζητάτε συνεχώς αλλαγές στο API, μπορείτε να ρυθμίσετε τα webhooks για να στέλνει το Twenty **δεδομένα** στο σύστημά σας κάθε φορά που προκύπτουν συγκεκριμένα γεγονότα (π.χ., όταν δημιουργείται μια νέα εγγραφή ή ενημερώνεται μια υπάρχουσα). Αυτό βοηθά τα εξωτερικά συστήματα να συγχρονίζονται με το Twenty άμεσα και αποτελεσματικά.
|
|
|
|
Με τα webhooks, το Twenty θα στείλει ένα αίτημα HTTP POST σε μια URL που καθορίζετε, περιέχοντας λεπτομέρειες για το γεγονός. Μπορείτε στη συνέχεια να διαχειριστείτε αυτά τα δεδομένα στην εφαρμογή σας (π.χ., να ενημερώσετε τη βάση δεδομένων σας, να ενεργοποιήσετε ροές εργασίας ή να στείλετε ειδοποιήσεις).
|
|
|
|
## Ρύθμιση ενός Webhook
|
|
|
|
Για να δημιουργήσετε ένα webhook στο Twenty, χρησιμοποιήστε τις ρυθμίσεις **APIs & Webhooks** στην εφαρμογή σας Twenty:
|
|
|
|
1. **Μεταβείτε στις Ρυθμίσεις:** Στην εφαρμογή σας Twenty, πηγαίνετε στις **Ρυθμίσεις → APIs & Webhooks**.
|
|
2. **Δημιουργία Webhook:** Κάτω από **Webhooks**, κάντε κλικ στο **+ Δημιουργία webhook**.
|
|
3. **Εισαγωγή URL:** Παρέχετε το URL τερματικού σημείου στο διακομιστή σας όπου θέλετε το Twenty να στέλνει αιτήματα webhook. Αυτό θα πρέπει να είναι μια δημόσια προσβάσιμη URL που μπορεί να διαχειριστεί αιτήματα POST.
|
|
4. **Αποθήκευση:** Κάντε κλικ στην επιλογή **Αποθήκευση** για να δημιουργήσετε το webhook. Το νέο webhook θα είναι ενεργό αμέσως.
|
|
|
|
Μπορείτε να δημιουργήσετε πολλαπλά webhooks αν χρειάζεστε να στέλνετε διαφορετικά γεγονότα σε διαφορετικά τερματικά σημεία. Κάθε webhook είναι ουσιαστικά μια συνδρομή για όλα τα σχετικά γεγονότα (αυτή τη στιγμή, το Twenty στέλνει όλους τους τύπους γεγονότων στην καθορισμένη URL· η δυνατότητα φιλτραρίσματος συγκεκριμένων τύπων γεγονότων μπορεί να είναι διαμορφώσιμη στη διεπαφή χρήστη). Αν χρειαστεί ποτέ να αφαιρέσετε ένα webhook, μπορείτε να το διαγράψετε από την ίδια σελίδα ρυθμίσεων (επιλέξτε το webhook και επιλέξτε διαγραφή).
|
|
|
|
## Γεγονότα και Περιεχόμενα
|
|
|
|
Μόλις ρυθμιστεί ένα webhook, το Twenty θα στείλει ένα αίτημα HTTP POST στην καθορισμένη URL όταν προκύψει ένα ενεργοποιόντα γεγονός στα δεδομένα του CRM σας. Κοινά γεγονότα που ενεργοποιούν τα webhooks περιλαμβάνουν:
|
|
|
|
- **Δημιουργία Εγγραφής:** π.χ. προσθήκη νέου ατόμου (`person.created`), δημιουργία νέας εταιρείας (`company.created`), δημιουργία σημείωσης (`note.created`), κ.λπ.
|
|
- **Ενημέρωση Εγγραφής:** π.χ. ενημέρωση πληροφοριών υπάρχοντος ατόμου (`person.updated`), επεξεργασία εγγραφής εταιρείας (`company.updated`), κ.λπ.
|
|
- **Διαγραφή Εγγραφής:** π.χ. διαγραφή ατόμου ή εταιρείας (`person.deleted`, `company.deleted`).
|
|
- **Άλλα Γεγονότα:** Αν υπάρχουν, άλλα γεγονότα αντικειμένων ή προσαρμοσμένες ενεργοποιήσεις (για παράδειγμα, αν ενημερώνονται εργασίες ή άλλα αντικείμενα, θα χρησιμοποιούνταν παρόμοιοι τύποι γεγονότων όπως `task.created`, `note.updated`, κ.λπ.).
|
|
|
|
Το αίτημα POST του webhook περιέχει ένα περιεχόμενο JSON στο σώμα του. Το περιεχόμενο θα περιλαμβάνει συνήθως τουλάχιστον δύο πράγματα: τον τύπο του γεγονότος και τα δεδομένα που σχετίζονται με αυτό το γεγονός (συνήθως την εγγραφή που δημιουργήθηκε/ενημερώθηκε). Για παράδειγμα, ένα webhook για ένα νεοδημιουργημένο άτομο μπορεί να στείλει ένα περιεχόμενο όπως:
|
|
|
|
```
|
|
{
|
|
"event": "person.created",
|
|
"data": {
|
|
"id": "abc12345",
|
|
"firstName": "Alice",
|
|
"lastName": "Doe",
|
|
"email": "alice@example.com",
|
|
"createdAt": "2025-02-10T15:30:45Z",
|
|
"createdBy": "user_123"
|
|
},
|
|
"timestamp": "2025-02-10T15:30:50Z"
|
|
}
|
|
```
|
|
|
|
Σε αυτό το παράδειγμα:
|
|
|
|
- `"event"` καθορίζει τι συνέβη (`person.created`).
|
|
- `"data"` περιέχει τις λεπτομέρειες της νέας εγγραφής (τις ίδιες πληροφορίες που θα λάβατε αν ζητούσατε αυτό το άτομο μέσω του API).
|
|
- `"timestamp"` είναι πότε συνέβη το γεγονός (σε UTC).
|
|
|
|
Το τερματικό σας σημείο πρέπει να είναι προετοιμασμένο να λαμβάνει τέτοια δεδομένα JSON μέσω POST. Συνήθως, θα αναλύετε το JSON, θα εξετάζετε τον τύπο του `"event"` για να κατανοήσετε τι συνέβη και στη συνέχεια θα χρησιμοποιείτε τα `"data"` αναλόγως (π.χ. να δημιουργήσετε νέο επαφή στο σύστημά σας ή να ενημερώσετε μια υπάρχουσα).
|
|
|
|
**Σημείωση:** Είναι σημαντικό να απαντήσετε με έναν **κωδικό κατάστασης HTTP της σειράς 2xx** από το τελικό σημείο του webhook σας για να αναγνωρίσετε την επιτυχή παραλαβή. Αν ο αποστολέας webhook του Twenty δεν λάβει απάντηση 2xx, μπορεί να θεωρήσει ότι η παράδοση απέτυχε. (Στο μέλλον, μπορεί να προσπαθήσει να επαναλάβει την αποστολή αποτυχημένων webhooks, οπότε πάντα επιδιώκετε να επιστρέφετε μια 200 OK το συντομότερο δυνατό μετά την επεξεργασία των δεδομένων).
|
|
|
|
## Επιβεβαίωση Webhook
|
|
|
|
Για να διασφαλίσετε την ασφάλεια των τελικών σημείων webhook, το Twenty περιλαμβάνει μια υπογραφή στην κεφαλίδα `X-Twenty-Webhook-Signature`.
|
|
|
|
Αυτή η υπογραφή είναι μια HMAC SHA256 διαδικασία του payload, υπολογισμένη χρησιμοποιώντας το μυστικό του webhook σας.
|
|
|
|
Για να επικυρώσετε την υπογραφή, θα πρέπει να:
|
|
|
|
1. Συνενώνετε τη χρονική σήμανση (από την κεφαλίδα `X-Twenty-Webhook-Timestamp`), μια άνω-κάτω τελεία, και τη συμβολοσειρά JSON του payload.
|
|
2. Υπολογίστε την HMAC SHA256 διαδικασία χρησιμοποιώντας το μυστικό του webhook σας ως κλειδί ().
|
|
3. Συγκρίνετε την αποτέλεσμα סעבודημ.Androidक़्धਖਵુਬਪਧTyping
|
|
|
|
Ακολουθεί ένα παράδειγμα σε Node.js:
|
|
|
|
```javascript
|
|
const crypto = require("crypto");
|
|
const timestamp = "1735066639761";
|
|
const payload = JSON.stringify({...});
|
|
const secret = "your-secret";
|
|
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
|
|
const signature = crypto.createHmac("sha256", secret)
|
|
.update(stringToSign)
|
|
.digest("hex");
|
|
``` |