Δημιουργία δικών σας ενσωματώσεων με Webhooks

Ο κανόνας «Αποστολή σε webhook» αυτοματοποιεί την αποστολή νέων αναρτήσεων από ροές RSS στο webhook endpoint που ορίζετε, μόλις γίνουν διαθέσιμες. Μπορείτε επίσης να επιλέξετε ποιες αναρτήσεις θα αποστέλλονται, ορίζοντας λέξεις-κλειδιά για φιλτράρισμα. Όταν μια νέα ανάρτηση πληροί τα κριτήριά σας, αποστέλλεται στο webhook endpoint σας ως αίτημα POST σε μορφή JSON.

Μορφή payload JSON

Κάθε αίτημα POST που αποστέλλεται στο webhook σας περιλαμβάνει δύο βασικά στοιχεία: το post και το feed.

Περιλαμβάνει επίσης μεταδεδομένα για την αναγνώριση του μηνύματος webhook. Το πεδίο version δηλώνει την έκδοση του API webhook του Feeder που χρησιμοποιείται. Η έκδοση παραμένει σταθερή στην τιμή 2023-06-26 και θα ενημερωθεί αν γίνουν αλλαγές που δεν είναι συμβατές με προηγούμενες εκδόσεις.

{
  "version": "2023-06-26",
  "message_id": "a unique UUID for this message, will be constant during retries",
  "feed": { ... },
  "post": { ... }
}

Το στοιχείο post περιέχει πληροφορίες για τη συγκεκριμένη ανάρτηση:

{
  "id": "The unique identifier of the post",
  "title": "The title of the post",
  "url": "The URL where the post can be accessed",
  "published": "The date and time when the post was published",
  "content": "The content of the post",
  "audio_url": "link to mp3 attached to post (if present)",
  "image_url": "link to image attached to post (if present)
}

Σημείωση: το published θα έχει τιμή null αν η ροή RSS δεν περιέχει έγκυρη ημερομηνία δημοσίευσης.

Το στοιχείο feed παρέχει πληροφορίες για τη ροή από την οποία προέρχεται η ανάρτηση:

{
  "id": "The unique identifier of the feed",
  "source_url": "The URL of the source, for example RSS/Atom feed URL",
  "public_url": "The source's self identified public URL",
  "title": "The title of the feed",
  "favicon": "The URL of the feed's favicon"
}

Ενδέχεται να προσθέσουμε νέα πεδία σε αυτά τα αντικείμενα στο μέλλον. Αν σας λείπει κάποιο στοιχείο, ενημερώστε μας.

Λογική επαναλήψεων

Αν ένα αίτημα αποτύχει, το Feeder επιχειρεί αυτόματα να το στείλει ξανά. Αν ένα αίτημα POST δεν λάβει κωδικό απόκρισης HTTP μεταξύ 200 και 399, θα προσπαθήσουμε να το στείλουμε ξανά σύμφωνα με το παρακάτω πρόγραμμα, με τους χρόνους σε δευτερόλεπτα:

• 1η επανάληψη: μετά από 5 δευτερόλεπτα
• 2η επανάληψη: μετά από 30 δευτερόλεπτα
• 3η επανάληψη: μετά από 60 δευτερόλεπτα
• 4η επανάληψη: μετά από 5 λεπτά
• 5η επανάληψη: μετά από 10 λεπτά
• 6η επανάληψη: μετά από 30 λεπτά
• 7η επανάληψη: μετά από 30 λεπτά
• 8η επανάληψη: μετά από 30 λεπτά

Λάβετε υπόψη ότι ο μηχανισμός επαναλήψεων ενεργοποιείται μόνο για πραγματικά συμβάντα ανάρτησης και δεν ισχύει για δοκιμαστικές ειδοποιήσεις. Οι χρόνοι ενδέχεται επίσης να αλλάξουν.

Αντιμετώπιση προβλημάτων

Αν προκύψουν σφάλματα, μπορείτε να τα δείτε στο αρχείο καταγραφής εκτελέσεων ενεργειών. Ανοίξτε τον κανόνα που δεν λειτουργεί και πατήστε «Άνοιγμα αρχείου καταγραφής σφαλμάτων».

Εκεί θα βρείτε περισσότερες λεπτομέρειες για τα webhook που απέτυχαν.

Ρύθμιση του webhook

Για να ρυθμίσετε το webhook:

1. Μεταβείτε στη σελίδα Κανόνες.
2. Δημιουργήστε έναν νέο κανόνα.
3. Προσθέστε όνομα, ροές και κριτήρια.
4. Στην ενότητα «Τι πρέπει να γίνει;», επιλέξτε «Αποστολή σε webhook».
5. Πληκτρολογήστε τη διεύθυνση URL του webhook στο αντίστοιχο πεδίο.
6. Για να βεβαιωθείτε ότι όλα έχουν ρυθμιστεί σωστά, μπορείτε να πατήσετε το κουμπί «Αποστολή δοκιμαστικού μηνύματος» για να σταλεί μια δοκιμαστική ειδοποίηση στο endpoint σας. Η ειδοποίηση είναι μόνο δοκιμαστική και, αν αποτύχει, δεν θα ενεργοποιηθεί ο μηχανισμός επαναλήψεων. Για να σταλεί η δοκιμαστική ανάρτηση, πρέπει να έχετε προσθέσει στον λογαριασμό σας τουλάχιστον μία ροή με αναρτήσεις.

Ασφάλεια: Επαλήθευση υπογραφών webhook

Για να βεβαιωθείτε ότι τα εισερχόμενα αιτήματα webhook προέρχονται πράγματι από το Feeder και δεν έχουν αλλοιωθεί, μπορείτε να επαληθεύσετε το μυστικό webhook που δημιουργείται για κάθε webhook. Κάθε αίτημα webhook περιλαμβάνει μια επικεφαλίδα X-Feeder-Signature με την υπογραφή HMAC-SHA256 του σώματος του αιτήματος.

Πώς λειτουργεί

1. Στις ρυθμίσεις του κανόνα, ενεργοποιήστε την επιλογή «Για προχωρημένους». Θα δείτε μια συμβολοσειρά στο πεδίο «Μυστικό webhook».
2. Όταν το Feeder στέλνει ένα webhook στο endpoint σας, υπολογίζει ένα hash HMAC-SHA256 του σώματος του αιτήματος JSON, χρησιμοποιώντας το μυστικό σας ως κλειδί.
3. Η υπογραφή που προκύπτει αποστέλλεται στην επικεφαλίδα X-Feeder-Signature, με πρόθεμα sha256=. Για παράδειγμα:

   X-Feeder-Signature: sha256=a1b2c3d4e5f6...

4. Στον διακομιστή σας, υπολογίστε ξανά το ίδιο hash HMAC-SHA256 χρησιμοποιώντας το ακατέργαστο σώμα του αιτήματος και το αντίγραφο του μυστικού σας και, στη συνέχεια, συγκρίνετέ το με την τιμή της επικεφαλίδας.

Γιατί να το χρησιμοποιήσετε;

• Γνησιότητα: Επιβεβαιώνει ότι το αίτημα στάλθηκε από το Feeder και όχι από τρίτο μέρος.
• Ακεραιότητα: Διασφαλίζει ότι το payload δεν τροποποιήθηκε κατά τη μεταφορά.

Επαλήθευση της υπογραφής

Για να επαληθεύσετε την υπογραφή:

1. Διαβάστε το ακατέργαστο σώμα του αιτήματος ως συμβολοσειρά, χωρίς να το αναλύσετε πρώτα.
2. Υπολογίστε το HMAC-SHA256 αυτής της συμβολοσειράς, χρησιμοποιώντας το μυστικό σας.
3. Συγκρίνετε την υπογραφή που υπολογίσατε με την τιμή της επικεφαλίδας X-Feeder-Signature χρησιμοποιώντας σύγκριση ασφαλή ως προς τον χρόνο, για να αποτρέψετε επιθέσεις χρονισμού.

Παράδειγμα: Node.js (Express)

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.FEEDER_WEBHOOK_SECRET;

function verifyFeederSignature(req, res, next) {
  const signature = req.headers["x-feeder-signature"];
  if (!signature) {
    return res.status(401).send("Missing signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  next();
}

// Important: use express.raw() so req.body is the raw string, not parsed JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Handle the webhook payload
    console.log("Received verified webhook:", payload);
    res.sendStatus(200);
  }
);

Σημαντικό: Για την επαλήθευση της υπογραφής πρέπει να έχετε πρόσβαση στο ακατέργαστο σώμα του αιτήματος. Αν το framework σας αναλύσει το σώμα JSON πριν υπολογίσετε το HMAC, η συμβολοσειρά που θα δημιουργηθεί ξανά μπορεί να διαφέρει από την αρχική και η υπογραφή δεν θα ταιριάζει. Στο Express, χρησιμοποιήστε το express.raw({ type: "application/json" }) στη διαδρομή του webhook, όπως φαίνεται παραπάνω.

Κάτι άλλο;

Έχετε ερωτήσεις; Στείλτε μας email στη διεύθυνση support@feeder.co.