Kimenő webhookok: payload és aláírás

A kimenő webhook az AutoPSEO riasztásait, ütemezett jelentéseit, tesztüzeneteit és jelentésösszegzéseit egy általad üzemeltetett végpontra küldi: üzenetenként egy HMAC-SHA256-tal aláírt JSON POST kérésként. Használhatod Zapier, Make, n8n, incidenskezelő eszköz vagy saját kód betáplálására; Slack- vagy Teams-fiókra nincs szükség. A cikkeket a webhelyedre kézbesítő webhookot keresed? Az a tartalommotorhoz tartozik: lásd a tartalomkézbesítést.

Webhook hozzáadása

1. Az Outbound webhooks szakaszban kattints a New webhook gombra.
2. Adj neki Name nevet, és illeszd be a végpont URL-jét. Nyilvános HTTPS címnek kell lennie: a sima http, a localhost, a .local vagy .internal végű nevek, a ponttal nem rendelkező hosztnevek, valamint a privát és link-local IP-címek elutasításra kerülnek.
3. Másold ki a mentés után megjelenő signing secret értéket (aláírási titok). Csak ez az egy alkalommal jelenik meg.
4. Kattints a Send test gombra egy test esemény elküldéséhez, majd csatold a webhookhoz az ütemezett jelentéseket vagy a riasztásokat.

Milyen egy webhookkérés

Minden üzenet egy POST kérés a következő fejlécekkel:

Íme egy forgalomesés-riasztás egy domain típusú property-hez, a 2026. október 12-i 06:00 UTC-s futásból, olvasható formázásban (a hálózaton tömör JSON megy, az id és a site_id értéke pedig kitalált):

{
  "id": "9b2e61f04c3a4d7e8f15a0b6c2d39e47",
  "event_type": "traffic_drop",
  "severity": "high",
  "site_id": "4f0c1e9a2b7d4c58",
  "site_url": "sc-domain:example.com",
  "occurred_at": "2026-10-12T06:00:04.183Z",
  "title": "Traffic drop: example.com",
  "text": "Clicks 1,500 vs 2,000 in the previous window (-25.0%).",
  "url": "https://app.autopseo.com/property/sc-domain%3Aexample.com",
  "payload": {
    "fields": [
      { "label": "Metric", "value": "clicks" },
      { "label": "Current", "value": "1,500" },
      { "label": "Baseline", "value": "2,000" },
      { "label": "Window", "value": "7 days (2026-10-05 → 2026-10-11 vs 2026-09-28 → 2026-10-04)" },
      { "label": "Change", "value": "-25.0%" }
    ],
    "table": null,
    "detector": "traffic_drop",
    "window": 7,
    "range": { "start": "2026-10-05", "end": "2026-10-11", "compStart": "2026-09-28", "compEnd": "2026-10-04" },
    "result": {
      "fired": true,
      "metric": "clicks",
      "value": 1500,
      "baseline": 2000,
      "change": -0.25,
      "severity": "high",
      "summary": "Clicks 1,500 vs 2,000 in the previous window (-25.0%)."
    }
  },
  "source": "autopseo"
}

A legfelső szintű mezők minden eseménynél azonosak:

Az arányok törtszámok: a -0.25 értékű change 25%-os csökkenést jelent, a 0.034 értékű ctr pedig 3,4%-ot.

Eseménytípusok

A result megismétli, amit a detektor mért: fired, metric, value, baseline, change (null, ha nincs mivel összehasonlítani), severity és summary, valamint az anomaly esetén a z, azaz a módosított z-pontszám. A totals és a previous a jelentés két időablakához tartalmazza a clicks, impressions, ctr és position értékeket. Hogy az egyes detektorok mit mérnek, azt az Alerts oldal írja le.

Az aláírás ellenőrzése

Az aláírás az AutoPSEO által elküldött pontos bájtok HMAC-SHA256 értéke, a webhook aláírási titkával kulcsolva, sha256= előtaggal és kisbetűs hexadecimális formában. Az ellenőrzés lépései:

1. Olvasd be a nyers kérés törzsét, mielőtt bármilyen JSON-elemzést végeznél. Az elemzés és az újrasorosítás megváltoztathatja a bájtokat.
2. Számítsd ki a HMAC-SHA256 értéket ezekre a bájtokra, a titkot szövegként használva: a 64 karakteres karakterláncot pontosan úgy, ahogy megjelenik, nem hexából visszafejtve.
3. Fűzd elé a sha256= előtagot, és az eredményt konstans idejű összehasonlítással vesd össze az X-AutoPSEO-Signature fejléccel.
4. Utasítsd el a kérést, ha eltérnek. Egyébként azonnal válaszolj 2xx státuszkóddal, a lassú munkát pedig végezd el utána.

Függőségmentes fogadó Node.js-hez:

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.AUTOPSEO_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);
    const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(raw).digest('hex'));
    const received = Buffer.from(String(req.headers['x-autopseo-signature'] || ''));
    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(204).end();
    const event = JSON.parse(raw.toString('utf8'));
    console.log(event.event_type, event.severity, event.site_url);
  });
}).listen(8080);

A hosszellenőrzés azért áll elöl, mert a Node timingSafeEqual függvénye hibát dob, ha a két puffer hossza eltér.

Kézbesítési szabályok

• Minden üzenet egyetlen próbálkozást kap, 10 másodperces időtúllépéssel. A 2xx-től eltérő válasz hibának számít, és a Delivery history (kézbesítési előzmények) rögzíti az állapotkóddal és a választörzs elejével együtt.
• Az átirányításokat a rendszer nem követi. A 3xx válasz hibával zárul, azzal a megjegyzéssel, hogy a végleges URL-t kell használni.
• Időzítővel semmi sem kerül újrapróbálásra. A sikertelen riasztás nem kerül elküldöttként megjelölésre, így a következő ellenőrzés újra kiértékeli, és ha még mindig aktív, elküldi: a legtöbb detektornál másnap reggel, az indexállapot-váltásoknál a következő órában. A sikertelen ütemezett jelentést ugyanabban az időszakban nem küldi újra a rendszer, ezért a végpont javítása után használd a Send now gombot.
• Az id kérésenként jön létre, vagyis egy kézbesítést azonosít, nem egy eseményt. A riasztások duplikátumainak kiszűréséhez kombináld az event_type, a site_url és az occurred_at dátumát: egy szabály property-nként legfeljebb egyszer posztol UTC-naponként, kivéve ha valaki lefuttatja a Test rule gombot.

Az aláírási titok

Az AutoPSEO az aláírási titkot egyszer mutatja meg, a webhook mentésekor, a lista pedig később már nem jeleníti meg. Tárold el rögtön a fogadó konfigurációjában, az általa védett végpont mellett.

Maga az URL titkosítva van tárolva, a lista csak a hosztját és az utolsó karaktereit mutatja. A webhook törlése az összes olyan szabályt is törli, amely rá posztol. Ha Teams-csatornában JSON helyett olvasható kártyát szeretnél, használd a Microsoft Teams integrációt.