Cara membuat integrasi sendiri dengan webhook

Aturan “Kirim ke Webhook” memungkinkan Anda mengotomatiskan pengiriman postingan baru dari feed RSS ke endpoint webhook yang ditentukan, segera setelah postingan tersedia. Anda juga dapat mengatur postingan yang dikirim dengan menentukan kata kunci sebagai filter. Saat postingan baru sesuai dengan kriteria, postingan tersebut akan dikirim ke endpoint webhook Anda sebagai permintaan POST berformat JSON.

Format payload JSON

Setiap permintaan POST yang dikirim ke webhook Anda berisi dua elemen utama, yaitu post dan feed.

Permintaan ini juga berisi elemen metadata untuk mengidentifikasi pesan webhook. Kolom version menyatakan versi API webhook Feeder yang digunakan. Versinya selalu 2023-06-26 dan akan diperbarui jika ada perubahan yang tidak kompatibel.

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

Elemen post berisi informasi tentang masing-masing postingan:

{
  "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)
}

Catatan: nilai published akan berupa null jika feed RSS tidak mencantumkan tanggal publikasi yang valid.

Elemen feed memberikan informasi tentang feed asal postingan:

{
  "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"
}

Ke depannya, kami mungkin menambahkan elemen ke objek ini. Jika ada informasi yang Anda perlukan tetapi belum tersedia, beri tahu kami.

Mekanisme percobaan ulang

Jika permintaan gagal, Feeder akan mencoba mengirimkannya lagi secara otomatis. Jika permintaan POST tidak menerima kode respons HTTP antara 200 dan 399, kami akan mencoba mengirimkannya kembali sesuai jadwal berikut, dalam satuan detik:

• Percobaan ulang 1: setelah 5 detik
• Percobaan ulang 2: setelah 30 detik
• Percobaan ulang 3: setelah 60 detik
• Percobaan ulang 4: setelah 5 menit
• Percobaan ulang 5: setelah 10 menit
• Percobaan ulang 6: setelah 30 menit
• Percobaan ulang 7: setelah 30 menit
• Percobaan ulang 8: setelah 30 menit

Perlu diketahui, mekanisme percobaan ulang ini hanya dijalankan untuk peristiwa postingan yang sebenarnya, bukan untuk notifikasi tes. Jeda waktunya juga dapat berubah.

Menelusuri masalah

Jika terjadi kesalahan, Anda dapat melihatnya di log eksekusi tindakan. Buka aturan yang bermasalah, lalu tekan “Buka log kesalahan”.

Di sana, Anda akan melihat detail lebih lanjut tentang webhook yang gagal.

Menyiapkan webhook

Untuk menyiapkan webhook:

1. Buka halaman Aturan.
2. Buat aturan baru.
3. Tambahkan nama, feed, dan kriteria Anda.
4. Di bagian “Apa yang harus terjadi?”, pilih “Kirim ke Webhook”.
5. Masukkan URL webhook Anda di kolom teks yang tersedia.
6. Untuk memastikan semuanya sudah disiapkan dengan benar, Anda dapat menggunakan tombol “Kirim pesan tes” untuk mengirim notifikasi tes ke endpoint Anda. Perlu diketahui, ini hanya tes dan mekanisme percobaan ulang tidak akan dijalankan jika gagal. Selain itu, agar pesan tes dapat dikirim, akun Anda harus memiliki setidaknya 1 feed yang sudah berisi postingan.

Keamanan: Memverifikasi tanda tangan webhook

Untuk memastikan permintaan webhook yang masuk benar-benar berasal dari Feeder dan tidak diubah, Anda dapat memverifikasi rahasia webhook yang dibuat untuk setiap webhook. Setiap permintaan webhook akan menyertakan header X-Feeder-Signature yang berisi tanda tangan HMAC-SHA256 dari isi permintaan.

Cara kerjanya

1. Di pengaturan aturan, aktifkan opsi “Lanjutan”. Anda akan melihat rangkaian karakter di kolom “Rahasia Webhook”.
2. Saat Feeder mengirim webhook ke endpoint Anda, Feeder menghitung hash HMAC-SHA256 dari isi permintaan JSON dengan rahasia Anda sebagai kunci.
3. Tanda tangan yang dihasilkan dikirim melalui header X-Feeder-Signature, dengan awalan sha256=. Contoh:

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

4. Di server Anda, hitung ulang hash HMAC-SHA256 yang sama menggunakan isi permintaan mentah dan salinan rahasia Anda, lalu bandingkan hasilnya dengan nilai di header.

Mengapa perlu digunakan?

• Keaslian: Memastikan permintaan dikirim oleh Feeder, bukan pihak ketiga.
• Integritas: Memastikan payload tidak diubah selama pengiriman.

Memverifikasi tanda tangan

Untuk memverifikasi:

1. Baca isi permintaan mentah sebagai string, jangan mengurainya terlebih dahulu.
2. Hitung HMAC-SHA256 dari string tersebut menggunakan rahasia Anda.
3. Bandingkan tanda tangan yang Anda hitung dengan nilai header X-Feeder-Signature menggunakan perbandingan yang aman terhadap serangan timing.

Contoh: 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);
  }
);

Penting: Anda harus mengakses isi permintaan mentah untuk memverifikasi tanda tangan. Jika framework Anda mengurai isi JSON sebelum Anda menghitung HMAC, string yang diserialisasi ulang mungkin berbeda dari aslinya sehingga tanda tangan tidak akan cocok. Di Express, gunakan express.raw({ type: "application/json" }) pada rute webhook seperti contoh di atas.

Ada pertanyaan lain?

Ada pertanyaan? Kirim email kepada kami di support@feeder.co.