Tworzenie własnych integracji za pomocą webhooków

Reguła „Opublikuj za pomocą Webhooka” automatyzuje wysyłanie nowych wpisów z kanałów RSS na wskazany endpoint webhooka, gdy tylko się pojawią. Możesz też określić, które wpisy mają być wysyłane, konfigurując słowa kluczowe do filtrowania. Gdy nowy wpis spełni kryteria, zostanie wysłany na endpoint webhooka jako żądanie POST z danymi w formacie JSON.

Format danych JSON

Każde żądanie POST wysłane do webhooka zawiera dwa główne elementy: post i feed.

Zawiera również metadane służące do identyfikacji wiadomości webhooka. Pole version określa wersję API webhooków Feeder, z której korzysta żądanie. Wersja ma stałą wartość 2023-06-26 i zostanie zaktualizowana w przypadku wprowadzenia niekompatybilnych zmian.

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

Element post zawiera informacje o konkretnym wpisie:

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

Uwaga: wartość published będzie równa null, jeśli kanał RSS nie poda prawidłowej daty publikacji.

Element feed zawiera informacje o kanale, z którego pochodzi wpis:

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

W przyszłości możemy dodawać nowe pola do tych obiektów. Jeśli czegoś brakuje, daj nam znać.

Ponawianie prób

Jeśli żądanie się nie powiedzie, Feeder automatycznie ponawia próbę. Jeśli żądanie POST nie otrzyma kodu odpowiedzi HTTP z zakresu od 200 do 399, spróbujemy wysłać je ponownie według określonego harmonogramu, podanego w sekundach:

• 1. ponowienie: po 5 sekundach
• 2. ponowienie: po 30 sekundach
• 3. ponowienie: po 60 sekundach
• 4. ponowienie: po 5 minutach
• 5. ponowienie: po 10 minutach
• 6. ponowienie: po 30 minutach
• 7. ponowienie: po 30 minutach
• 8. ponowienie: po 30 minutach

Pamiętaj, że mechanizm ponawiania prób jest uruchamiany tylko w przypadku rzeczywistych zdarzeń związanych z wpisami i nie dotyczy powiadomień testowych. Podane odstępy czasu mogą się również zmienić.

Rozwiązywanie problemów

Jeśli wystąpią błędy, znajdziesz je w dzienniku wykonań akcji. Otwórz niedziałającą regułę i kliknij „Otwórz dziennik błędów”.

Znajdziesz tam więcej informacji o nieudanych żądaniach webhooka.

Konfigurowanie webhooka

Aby skonfigurować webhook:

1. Przejdź na stronę Zasady.
2. Utwórz nową regułę.
3. Podaj nazwę, wybierz kanały i określ kryteria.
4. W sekcji „Co powinno się stać?” wybierz „Opublikuj za pomocą Webhooka”.
5. Wpisz adres URL webhooka w wyznaczonym polu tekstowym.
6. Aby sprawdzić, czy wszystko zostało poprawnie skonfigurowane, możesz kliknąć przycisk „Wyślij wiadomość testową”, aby wysłać powiadomienie testowe do endpointu. Pamiętaj, że to tylko test. Jeśli się nie powiedzie, mechanizm ponawiania prób nie zostanie uruchomiony. Aby wysłać testowy wpis, musisz mieć na koncie co najmniej jeden kanał z dodanymi wpisami.

Bezpieczeństwo: weryfikowanie podpisów webhooka

Aby upewnić się, że przychodzące żądania webhooka rzeczywiście pochodzą od Feeder i nie zostały zmodyfikowane, możesz zweryfikować wygenerowany dla każdego webhooka sekret. Każde żądanie webhooka będzie zawierało nagłówek X-Feeder-Signature z podpisem HMAC-SHA256 treści żądania.

Jak to działa

1. W ustawieniach reguły włącz opcję „Zaawansowane”. W polu „Sekret webhooka” zobaczysz ciąg znaków.
2. Gdy Feeder wysyła webhook do endpointu, oblicza skrót HMAC-SHA256 treści żądania JSON, używając Twojego sekretu jako klucza.
3. Wynikowy podpis jest wysyłany w nagłówku X-Feeder-Signature z prefiksem sha256=. Na przykład:

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

4. Na swoim serwerze oblicz ponownie ten sam skrót HMAC-SHA256, używając surowej treści żądania oraz swojej kopii sekretu, a następnie porównaj go z wartością w nagłówku.

Po co to robić?

• Autentyczność: potwierdza, że żądanie zostało wysłane przez Feeder, a nie przez podmiot trzeci.
• Integralność: gwarantuje, że dane nie zostały zmodyfikowane podczas przesyłania.

Weryfikowanie podpisu

Aby zweryfikować podpis:

1. Odczytaj surową treść żądania jako ciąg znaków, nie parsuj jej wcześniej.
2. Oblicz HMAC-SHA256 tego ciągu, używając swojego sekretu.
3. Porównaj obliczony podpis z wartością nagłówka X-Feeder-Signature, stosując porównanie odporne na ataki czasowe.

Przykład: 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);
  }
);

Ważne: Do weryfikacji podpisu musisz użyć surowej treści żądania. Jeśli framework sparsuje treść JSON przed obliczeniem HMAC, ponownie zserializowany ciąg może różnić się od oryginału, a podpis nie będzie pasować. W Express użyj express.raw({ type: "application/json" }) na trasie webhooka, jak pokazano powyżej.

Coś jeszcze?

Masz pytania? Napisz do nas na adres support@feeder.co.