Odchozí webhooky: payload a podpis

Odchozí webhook odesílá upozornění, plánované reporty, testovací zprávy a souhrny reportů z AutoPSEO na endpoint, který provozujete, a to jako jeden JSON POST na každou zprávu podepsaný pomocí HMAC-SHA256. Hodí se pro napojení na Zapier, Make, n8n, nástroj pro řešení incidentů nebo vlastní kód; účet na Slack ani Teams k tomu nepotřebujete. Hledáte webhook, který doručuje články na váš web? Ten patří k content enginu: viz doručování obsahu.

Přidání webhooku

1. V sekci Outbound webhooks klikněte na New webhook.
2. Zadejte Name a vložte URL endpointu. Musí jít o veřejné HTTPS: prosté http, localhost, názvy končící na .local nebo .internal, hostitele bez tečky a privátní či link-local IP adresy systém odmítne.
3. Po uložení si zkopírujte signing secret. Zobrazí se pouze tentokrát.
4. Kliknutím na Send test odešlete událost test a potom k webhooku připojte plánované reporty nebo upozornění.

Jak vypadá požadavek webhooku

Každá zpráva je POST s těmito hlavičkami:

Zde je upozornění na pokles návštěvnosti pro doménovou property z běhu v 06:00 UTC dne 12. října 2026, zformátované pro čtení (při odeslání jde o kompaktní JSON a hodnoty id a site_id jsou vymyšlené):

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

Pole na nejvyšší úrovni jsou u všech událostí stejná:

Poměrové hodnoty jsou zlomky: change o hodnotě -0.25 znamená pokles o 25 % a ctr o hodnotě 0.034 odpovídá 3,4 %.

Typy událostí

result opakuje, co detektor naměřil: fired, metric, value, baseline, change (null, pokud není s čím porovnávat), severity a summary, a u anomaly navíc z, modifikované z-skóre. totals a previous obsahují clicks, impressions, ctr a position pro dvě okna reportu. Co který detektor měří, popisuje stránka Alerts.

Jak ověřit podpis

Podpis je HMAC-SHA256 přesných bajtů, které AutoPSEO odeslalo, s klíčem v podobě signing secretu webhooku, zapsaný jako sha256= plus malá hexadecimální čísla. Ověření probíhá takto:

1. Načtěte surové tělo požadavku dříve, než ho začnete parsovat jako JSON. Opětovné parsování a serializace může bajty změnit.
2. Spočítejte HMAC-SHA256 nad těmito bajty a secret použijte jako text: 64znakový řetězec přesně tak, jak se zobrazuje, nikoli dekódovaný z hexadecimální podoby.
3. Přidejte předponu sha256= a výsledek porovnejte s hlavičkou X-AutoPSEO-Signature v konstantním čase.
4. Pokud se neshodují, požadavek odmítněte. Jinak ihned odpovězte stavem 2xx a pomalejší práci udělejte až potom.

Přijímač pro Node.js bez závislostí:

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);

Kontrola délky je na prvním místě, protože funkce timingSafeEqual v Node.js vyhodí chybu, pokud mají oba buffery různou délku.

Pravidla doručování

• Každá zpráva dostane jeden pokus s časovým limitem 10 sekund. Jakákoli jiná odpověď než 2xx se počítá jako selhání a uloží se do Delivery history spolu se stavovým kódem a začátkem těla vaší odpovědi.
• Přesměrování se nenásledují. Odpověď 3xx skončí selháním s upozorněním, že je třeba použít koncovou URL.
• Nic se neopakuje podle časovače. Neúspěšné upozornění se neoznačí jako odeslané, takže ho další kontrola vyhodnotí znovu a odešle, pokud se stále spouští: u většiny detektorů další ráno, u změn indexace další hodinu. Neúspěšný plánovaný report se ve stejném období znovu neodešle, proto po opravě endpointu použijte Send now.
• id vzniká pro každý požadavek zvlášť, takže identifikuje doručení, nikoli událost. Pro deduplikaci upozornění zkombinujte event_type, site_url a datum z occurred_at: pravidlo odešle nejvýše jedno upozornění na property za den UTC, pokud někdo nespustí Test rule.

Signing secret

AutoPSEO zobrazí signing secret jen jednou, při uložení webhooku, a seznam ho už nikdy neukáže. Uložte si ho hned do konfigurace svého přijímače, vedle endpointu, který chrání.

Samotná URL se ukládá zašifrovaně a seznam zobrazuje pouze hostitele a poslední znaky. Smazáním webhooku se smažou i všechna pravidla, která na něj odesílají. Chcete-li v kanálu Microsoft Teams místo JSONu přehlednou kartu, použijte Microsoft Teams.