Webhooky

Webhooky umožňujú externému systému prijímať oznámenia v reálnom čase, keď v ProcureSwift nastane nejaká udalosť — napríklad keď je vytvorená objednávka, keď sa zmení stav faktúry alebo keď je prijatá cenová ponuka. Namiesto pravidelného dopytovania API externý systém zaregistruje URL adresu a ProcureSwift pri každej sledovanej udalosti odošle JSON payload na túto adresu.

Kde to nájsť

V hlavnom menu otvorte Webhooky (/webhooks). Stránka vyžaduje oprávnenie Webhooks / View.

Dostupné udalosti

Odber môže sledovať jednu alebo viac z nasledujúcich udalostí:

• purchase_order.created
• purchase_order.status_changed
• invoice.created
• invoice.status_changed
• rfq.published
• rfp.published
• delivery_note.created
• quotation.received
• proposal.received

Vytvorenie odberu webhooku

1. Kliknite na Pridať webhook.
2. Vyplňte formulár:
   • URL webhooku — verejne dostupný HTTPS endpoint, na ktorý budú odosielané payloady udalostí. Povinné pole.
   • Udalosti — zaškrtnite aspoň jednu udalosť na sledovanie. Webhook sa aktivuje iba pre zaškrtnuté udalosti.
3. Kliknite na Vytvoriť.

Jednorazové zobrazenie tajného kľúča

Ihneď po vytvorení sa podpisový tajný kľúč webhooku zobrazí jednorazovo v potvrdzovacom dialógu. Skopírujte ho a bezpečne uložte na prijímacom systéme — platforma ho už nikdy nezobrazí. Tajný kľúč je potrebný na overenie, že prichádzajúce požiadavky skutočne pochádzajú z ProcureSwift (pozri Overenie podpisu nižšie).

Správa odberov

Tabuľka Odbery na /webhooks zobrazuje: URL adresu, udalosti, stav, čas posledného odoslania, počet po sebe idúcich chýb a dátum vytvorenia.

Akcie pre každý riadok:

• Prepínač stavu — prepnutím aktivujete alebo deaktivujete odber bez jeho vymazania. Deaktivované webhooky prestanú prijímať udalosti, ich konfigurácia sa však zachová.
• Upraviť (ikona ceruzky) — zmena URL adresy alebo zoznamu sledovaných udalostí.
• Odstrániť (ikona koša) — trvalé odstránenie odberu.

Stĺpec Séria zlyhaní počíta po sebe idúce neúspešné pokusy o doručenie. Nenulová hodnota znamená, že prijímajúci endpoint odmieta požiadavky alebo je nedostupný. Dlhá séria chýb môže spôsobiť, že platforma automaticky spomalí odosielanie alebo webhook deaktivuje.

Overenie podpisu (HMAC)

Každá požiadavka webhooku obsahuje hlavičku s podpisom vypočítaným z tela požiadavky pomocou podpisového tajného kľúča odberu. Prijímajúci systém musí tento podpis overiť pred spracovaním payloadu — bez tohto overenia by mohol ktokoľvek, kto pozná URL adresu, odosielať falošné udalosti.

Základný postup overenia na strane prijímača:

1. Načítajte surové telo požiadavky.
2. Vypočítajte HMAC-SHA256(secret, body).
3. Porovnajte výsledok, v konštantnom čase, s hlavičkou podpisu v požiadavke.
4. Ak sa nezhodujú, požiadavku odmietnite.

Tajný kľúč uložte v konfiguračnom prostredí prijímača — nikdy v zdrojovom kóde.

Opakované pokusy

Ak prijímajúci endpoint vráti stavový kód iný ako 2xx alebo vyprší časový limit, platforma zopakuje doručenie podľa harmonogramu s postupne sa zvyšujúcimi intervalmi. Stĺpec Naposledy spustené zobrazuje čas posledného pokusu (úspešného alebo nie) a stĺpec Séria zlyhaní ukazuje, koľko po sebe idúcich pokusov zlyhalo od posledného úspešného doručenia. Úspešné doručenie vynuluje počítadlo chýb.

Rotácia tajného kľúča

Podpisový tajný kľúč sa vygeneruje pri vytvorení webhooku a zobrazí sa jednorazovo. Na jeho rotáciu odstráňte odber a vytvorte nový (čím sa vygeneruje nový tajný kľúč), potom aktualizujte tajný kľúč na prijímacom systéme. Koordinujte zmenu tak, aby prijímajúci systém dôveroval novému tajnému kľúču ešte pred odstránením starého odberu.

Tipy

• Pomocou Upraviť pridajte nové typy udalostí do existujúceho odberu namiesto vytvárania samostatného webhooku pre každú udalosť.
• Navrhnite prijímač ako idempotentný — platforma môže opakovať doručenie, takže rovnaká udalosť môže prísť viackrát. Na deduplikáciu použite ID udalosti v payloade.
• Odpovedajte s 200 OK hneď po uložení payloadu a spracujte ho asynchrónne. Dlho bežiace handlery môžu spôsobiť opakované pokusy.
• Sledujte stĺpec Séria zlyhaní alebo nastavte upozornenie, ak hodnota presiahne nulu.

Oprávnenia

Akcia	Potrebné oprávnenie
Zobrazenie odberov	Webhooks / View
Pridanie webhooku	Webhooks / Create
Úprava webhooku, prepnutie stavu	Webhooks / Update
Vymazanie webhooku	Webhooks / Delete

Súvisiace príručky

• API kľúče a audit logy — pre odchádzajúce API volania z vašich systémov do ProcureSwift.