Webhooky

Webhooky posílají oznámení z Freela do jiné aplikace po vybrané události. Váš program tak může zapisovat nové úkoly nebo výkazy do firemního reportu bez pravidelného dotazování Freela.

Po vybrané události Freelo odešle oznámení a související data na přijímací URL. Při chybě doručení pokus opakuje podle pravidel níže.

Typy webhooků

Ve formuláři zvolíte, na které události má webhook reagovat:

• Úkoly: task_created (vytvoření), task_edited (úprava), task_finished (dokončení), task_activated (znovuotevření), task_deleted (smazání), task_undeleted (obnovení) a task_moved (přesun).
• To-Do listy: tasklist.
• Poznámky: note.
• Komentáře: comment.
• Výkazy práce: workreport.

Jde o názvy voleb ve formuláři. Například volba tasklist může odpovídat konkrétní události tasklist_edited v přijatém požadavku; název volby proto nezaměňujte s úplnou hodnotou type v JSON. Webhook můžete omezit na vybrané projekty nebo zapnout pro všechny projekty.

Jak webhooky fungují

Přijímací URL musí používat HTTPS. Za úspěšné doručení Freelo považuje odpověď s HTTP stavovým kódem 2xx; přesměrování 3xx nenásleduje. Při neúspěchu se pokusí o doručení až desetkrát, než webhook deaktivuje. Prodlevy mezi pokusy exponenciálně rostou, poslední pokus následuje po pěti hodinách.

Freelo posílá na zadanou adresu požadavek s tělem ve formátu JSON. Základní obálka uvádí typ události, čas jejího vzniku a autora. Obsah objektu data se liší podle události a dotčené položky.

Po odeslání Freelo uloží záznam doručení včetně odpovědi přijímající aplikace. Historie posledních pěti pokusů slouží k hledání chyb. Jde o záznam komunikace, nikoli o další příkaz poslaný do vaší aplikace.

Jak nastavit nový webhook

Nový webhook zadáte přímo ve Freelu. Přes avatar v pravém horním rohu přejdete do Nastavení > Webhooky. Stačí kliknout na Přidat webhook. Dále doplníte URL adresu, na kterou máme data z Freela posílat, zvolíte jaké typy informací a z jakých projektů vás zajímají. Potom klikněte na Uložit.

Po přidání webhooku se zobrazí na seznamu webhooků.

Jak otestovat nastavení webhooku

Doručení můžete ověřit například pomocí služby Webhook.site. Vygeneruje vlastní přijímací URL a zobrazí požadavky, které na ni dorazí. Použijte svou adresu a demonstrační data: služba obdrží také obsah odesílaného úkolu nebo jiné položky.

V nástroji Webhook.site se poté přehledně zobrazí všechny požadavky a zaslaná data ve formátu JSON.

Po provedení zvolené akce ve Freelu zkontrolujte přijatý požadavek na Webhook.site. Například vytvoření úkolu vyvolá událost task_created, pokud ji máte pro daný projekt zapnutou. Ve Freelu pak můžete kontrolovat historii doručení.

Princip zpracování ukazuje oficiální PHP příklad přijímače webhooku. Načte tělo požadavku, dekóduje JSON a při typu task_deleted sestaví e-mail z údajů o autorovi a smazaném úkolu. Jde o jednoduchý výchozí příklad, který upravíte pro svou aplikaci; není to specifikace všech událostí.

Historie patří ke konkrétnímu webhooku v přehledu Webhooky. Na historickém přehledu výše má každý řádek vlastní nabídku pod třemi tečkami vpravo. Následující historický dialog ukazuje posledních pět doručení; současný název položky pro otevření historie zde není doložen. Zelený záznam s kódem 200 znamená úspěšnou HTTP odpověď příjemce, červený s kódem 410 chybu. Podle kódu pak hledejte příčinu na přijímací straně.

Příklady

Následující příklady ukazují, jak události využít a kterou volbu zapnout ve formuláři. Nejde o kód pro nastavení webhooku ani o úplnou technickou specifikaci. Při implementaci pracujte se skutečně přijatým JSON: názvy jeho klíčů i hodnoty type přebírejte přesně, včetně podtržítek a velikosti písmen.

Vytvoření úkolu

Zapněte task_created, pokud má přijímací aplikace reagovat na nový úkol, například ho zapsat do firemního reportu. Následující výběr polí je přesně přepsaný z autentického požadavku na historickém snímku z 1. června 2020. Ostatní pole včetně osobních údajů jsou vynechána; nejde o celý požadavek ani záruku dnešního schématu.

{
  "type": "task_created",
  "created_at": "2020-06-01T14:08:19+02:00",
  "data": {
    "id": 25941,
    "name": "Nový úkol poslaný na Webhook",
    "priority_enum": null,
    "due_date": null,
    "due_date_end": null,
    "date_add": "2020-06-01T14:08:19+02:00"
  }
}

V tomto požadavku je type označení události a data obsahuje údaje úkolu. Klíče priority_enum a due_date_end mají podtržítka. Snímek zároveň ukazuje klíč author.fullname; jméno je zakryté. Také tyto zápisy popisují konkrétní historický požadavek, nikoli jednotné schéma všech událostí.

Seznam úkolů

Pro události To-Do listů zapněte tasklist. Můžete tak navázat zpracování změn seznamů v externím systému. Historie výše dokládá konkrétní událost tasklist_edited; zápis s mezerami task list edited této zachycené události neodpovídá. Tělo požadavku na snímku historie není, proto z něj nelze odvodit další JSON klíče.

Poznámka

Pro události poznámek vyberte note. Přijímací aplikace může například upozornit na změnu projektové poznámky. Konkrétní operaci rozlište podle skutečně přijatého type; obecná volba note sama neurčuje přesný název události ani strukturu jejího data.

Komentář

Události komentářů zapnete volbou comment. Můžete je využít třeba k navazujícímu upozornění v jiném systému. Z přijatých dat zjistěte, ke kterému komentáři a úkolu se událost vztahuje. Přesné názvy klíčů přebírejte z požadavku; nevytvářejte je překladem názvů ve Freelu.

Přesun úkolu

Volba task_moved slouží pro přesun úkolu. Integrace na ni může reagovat aktualizací umístění úkolu v externím systému. Při zpracování zkontrolujte, jak přijatá data rozlišují původní a nové umístění. Potřebujete-li další aktuální údaje o úkolu, můžete je dočíst přes API.

Změna úkolu

Pro úpravy úkolů zapněte task_edited. Integrace tak může reagovat na změny existujících úkolů; samostatné volby jsou například pro dokončení a přesun. Nespoléhejte na to, že jediný typ pokryje každou akci nebo že každý požadavek obsahuje všechna pole úkolu.

Při ověřování své integrace projděte změny, které potřebujete zpracovávat: název, popis, termín, prioritu, řešitele, štítky, stav, podúkoly, vlastní pole či časový odhad. U každé ověřte konkrétní doručenou událost a její data; tento výčet není zárukou, že všechny uvedené změny spouštějí task_edited.

Výkaz práce

Výkazy práce zapnete volbou workreport. Přijímací aplikace pak může přenášet údaje do docházky, reportu nebo účetního systému. Před mapováním polí ověřte konkrétní typ operace, časové a finanční údaje i návaznost na úkol ve skutečně přijatém požadavku. Název volby workreport není úplným schématem takového požadavku.

Na co se webhooky hodí?

Možností je opravdu hodně. Pro inspiraci se podívejte na pár příkladů:

1. Zautomatizujte si nastavení štítků pro nové úkoly v konkrétních To-Do listech.
2. Pošlete upozornění, pokud někdo smaže úkol v projektu. Nebo třeba jen v případě externisty.
3. Posílejte upozornění na hotové úkoly do Slacku.
4. Synchronizujte výkaz práce do druhého systému (např. Pohoda), docházkové aplikace nebo Google Sheets. Navazující přenos zajistí vaše přijímací integrace; webhook jí oznámí událost bez pravidelného dotazování Freela.