Szabadságkérelem-értesítések Slackbe Collabin webhookokkal

Amikor valaki szabadságot kér, az érintettek ott értesüljenek róla, ahol amúgy is dolgoznak — a Slackben. Ez az útmutató a Collabin webhookjait köti össze egy Slack-csatornával, az elejétől a végéig: feliratkozunk a szabadság-eseményekre, kriptográfiailag ellenőrizzük a kézbesítéseket, és formázott üzenetet küldünk. Ugyanez a minta működik Microsoft Teamsszel, Discorddal, n8n-nel, Make-kel vagy bármilyen belső rendszerrel is.

Hogyan működnek a Collabin webhookok

A webhook egy általad üzemeltetett HTTPS-végpont; a Collabin POST kéréssel hívja meg, valahányszor egy feliratkozott esemény bekövetkezik. Két esemény érhető el:

Minden kézbesítés egy JSON-boríték:

{
  "event": "leave.created",
  "timestamp": "2026-06-13T09:30:00Z",
  "delivery_id": "f3a91c0d2b8e4a17",
  "organization_id": 42,
  "data": {
    "id": 1337,
    "user_id": 7,
    "user": { "id": 7, "name": "Kiss Janka" },
    "leave_type_id": 1,
    "leave_type": { "id": 1, "name": "Szabadság" },
    "start_date": "2026-07-01T00:00:00Z",
    "end_date": "2026-07-05T00:00:00Z",
    "is_half_day": false,
    "status": "PENDING"
  }
}

Minden kérést három fejléc kísér:

• X-Collabin-Event — az esemény neve, így a body feldolgozása nélkül is tudsz útválasztani.
• X-Collabin-Delivery — egyedi kézbesítési azonosító, deduplikációhoz és loghoz hasznos.
• X-Collabin-Signature — sha256=<hex>, a nyers kérés-body HMAC-SHA256 aláírása a webhookod titkos kulcsával. Mindig ellenőrizd, mielőtt megbízol a payloadban.

A Collabin legfeljebb 10 másodpercet vár, és bármilyen 2xx választ sikernek tekint — válaszolj gyorsan, a tényleges munkát végezd aszinkron módon.

Mire lesz szükséged

• Collabin-fiókra Pro csomaggal (a webhookok kezelése ehhez kötött).
• Egy Slack-munkaterületre, ahol incoming webhookot tudsz létrehozni.
• Egy helyre, ahol ~40 sornyi Node.js futhat: kis VPS, Cloud Run, serverless függvény — bármi, aminek publikus HTTPS-címe van.

1. lépés: Slack incoming webhook létrehozása

A Slackben hozz létre egy appot (vagy használj meglévőt), engedélyezd az Incoming Webhooks funkciót, és adj hozzá egyet ahhoz a csatornához, ahová az értesítések érkezzenek. A Slack ad egy URL-t, valahogy így: https://hooks.slack.com/services/T000/B000/XXXX. Kezeld titokként.

2. lépés: A híd telepítése

Ez a kis Express-szerver ellenőrzi a Collabin aláírását, és olvasható üzenetet továbbít a Slackbe:

const crypto = require('crypto');
const express = require('express');

const COLLABIN_SECRET = process.env.COLLABIN_WEBHOOK_SECRET;
const SLACK_URL = process.env.SLACK_WEBHOOK_URL;

const app = express();
// A nyers body kell — az aláírás pontosan ezekre a bájtokra készül.
app.use(express.raw({ type: 'application/json' }));

app.post('/collabin-webhook', async (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', COLLABIN_SECRET)
    .update(req.body)
    .digest('hex');

  const received = req.get('X-Collabin-Signature') || '';
  const valid = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

  if (!valid) {
    return res.status(401).send('invalid signature');
  }

  // Azonnal nyugtázunk; a Collabinnak csak egy 2xx kell.
  res.status(200).send('ok');

  const payload = JSON.parse(req.body.toString('utf8'));
  const leave = payload.data;
  const who = leave.user ? leave.user.name : `#${leave.user_id} felhasználó`;
  const type = leave.leave_type ? leave.leave_type.name : 'Szabadság';
  const from = leave.start_date.slice(0, 10);
  const to = leave.end_date.slice(0, 10);

  const text = payload.event === 'leave.created'
    ? `:palm_tree: *${who}* szabadságot kért (*${type}*): *${from}* – *${to}*`
    : `:bell: *${who}* kérelme (${type}, ${from} – ${to}) új státusza: *${leave.status}*`;

  await fetch(SLACK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text })
  });
});

app.listen(process.env.PORT || 3000);

Két részlet fontosabb, mint amilyennek látszik:

1. A nyers body alapján ellenőrizz. Ha a keretrendszer előbb JSON-ná alakítja, majd te újraszerializálod, a kulcssorrend vagy a whitespace változása elrontja a HMAC-et. A pontos bájtokat olvasd.
2. Konstans idejű összehasonlítást használj (crypto.timingSafeEqual), hogy az ellenőrzés ne szivárogtasson időzítési információt.

3. lépés: Webhook regisztrálása a Collabinban

1. A Collabin felületén nyisd meg a Webhookok menüpontot.
2. Az Új webhook gombbal vedd fel: illeszd be a végpontod URL-jét, és válaszd ki az eseményeket (leave.created, leave.status_changed, vagy mindkettő).
3. A Collabin a webhookhoz titkos kulcsot rendel — ezt másold a híd COLLABIN_WEBHOOK_SECRET környezeti változójába.

Adj be egy próba-szabadságkérelmet, és az üzenetnek egy-két másodpercen belül meg kell jelennie a Slackben.

Üzemeltetési tudnivalók

• Nincs automatikus újrapróbálkozás. A kézbesítés „tüzelj és felejtsd el" alapon működik: ha a végpontod elérhetetlen, vagy nem 2xx státuszt ad vissza, az adott esemény nem kerül újraküldésre — a sikertelen kísérlet viszont bekerül a Collabin rendszerhiba-naplójába, így pontosan látod, mi és mikor romlott el.
• Hibakeresésnél inaktiválj, ne törölj: a webhook kikapcsolható és később visszakapcsolható a konfiguráció újbóli megadása nélkül.
• Fogyasztónként egy webhook. Minden webhooknak saját titka van; minden downstream rendszer kapjon saját regisztrációt közös végpont helyett.

A Slacken túl

A fenti híd szándékosan minimális. Ugyanezzel az ellenőrzött payloaddal automatikusan out-of-office státuszt állíthatsz, belső HR-rendszerbe szinkronizálhatsz, vagy no-code eszközt etethetsz — irányíts egy n8n vagy Make webhook-triggert a Collabinra, az aláírás-ellenőrzést pedig tedd egy function lépésbe.