Přejít na hlavní obsah
Webhooky umožňují AgencyHandy okamžitě odesílat data do vašich externích systémů, jakmile dojde ke změně — bez nutnosti opakovaného dotazování. Když nastane nakonfigurovaná událost (například je aktualizována objednávka nebo vytvořen tiket), AgencyHandy odešle HTTP POST požadavek s JSON datovým obsahem na vámi zadanou adresu URL endpointu. To usnadňuje synchronizaci externích nástrojů, jako jsou CRM systémy, fakturační systémy nebo vlastní dashboardy, s vaším workspace AgencyHandy v reálném čase.
Workspaces s plánem Business Pro podporují až 30 000 webhook událostí za fakturační období. Před nastavením automatizací s vysokým objemem zkontrolujte limity svého plánu.

​
Podporované události

Webhook lze přihlásit k odběru libovolné kombinace následujících událostí:
KategorieUdálosti
SlužbaVytvořena, aktualizována, smazána
ObjednávkaVytvořena, aktualizována, smazána
ÚkolVytvořen, přiřazen, dokončen, aktualizován
FakturaZměněn stav
Klient / UživatelPřidán nový klient, klient/uživatel smazán
NávrhOdeslán, přijat, schválen, zamítnut
TiketVytvořen, přiřazen, změněn stav
PlatbaPřijata, neúspěšná
Servisní balíčekVytvořen, aktualizován, smazán

​
Vytvoření webhooku

1

Přejděte na Správu webhooků

V levém postranním panelu přejděte na Integrace → Správa webhooků.
2

Ověřte svůj token

Kliknutím na tlačítko Správa ověřte svůj webhook token. Tento token slouží k podpisu odchozích datových obsahů, abyste mohli ověřit, že pocházejí z AgencyHandy.
3

Vytvořte nový webhook

Kliknutím na Vytvořit nový webhook otevřete formulář konfigurace webhooku.
4

Zadejte adresu URL endpointu

Do pole Adresa URL endpointu zadejte URL externího systému, který má přijímat data webhooku. Musí se jednat o veřejně přístupný POST endpoint.
5

Vyberte typ obsahu

Jako typ obsahu zvolte JSON. AgencyHandy odesílá všechny datové obsahy webhooků jako application/json.
6

Vyberte události webhooku

Vyberte každou událost, která má spustit tento webhook. Můžete vybrat události z více kategorií — například Objednávka: Vytvořena a Faktura: Změněn stav mohou obě směřovat na stejný endpoint.
7

Aktivujte webhook

Zapněte přepínač Aktivní. Když je webhook aktivní, AgencyHandy doručuje datové obsahy pro všechny vybrané události na váš endpoint v reálném čase.
8

Uložte konfiguraci

Zkontrolujte nastavení a klikněte na Uložit. Webhook se zobrazí v seznamu a okamžitě začne doručovat události.

​
Testování webhooku

Po vytvoření webhooku odešlete testovací datový obsah, abyste ověřili, že je váš endpoint dostupný a správně zpracovává data.
1

Otevřete webhook

Ze seznamu Správa webhooků klikněte na webhook, který chcete testovat.
2

Klikněte na Testovat událost

Na stránce detailu webhooku klikněte na tlačítko Testovat událost.
3

Vyberte testovací událost

Ze seznamu událostí nakonfigurovaných na tomto webhooku vyberte ukázkovou událost (např. Objednávka: Vytvořena).
4

Odešlete testovací datový obsah

Klikněte na Odeslat. AgencyHandy odešle ukázkový datový obsah na adresu URL vašeho endpointu.
5

Ověřte výsledek

Zkontrolujte, zda testovací datový obsah dorazil do vašeho externího systému a byl zpracován podle očekávání. Zpět v AgencyHandy klikněte do webhooku a zkontrolujte jeho historii — můžete zobrazit celý požadavek, odpověď vrácenou vaším endpointem a v případě potřeby znovu doručit jakoukoli minulou událost.
Během nastavení použijte nástroj jako Webhook.site nebo RequestBin jako dočasný endpoint k prozkoumání přesné struktury datového obsahu, než zapojíte skutečný systém.

​
Ověřování datových obsahů webhooků

Každý odchozí požadavek webhooku z AgencyHandy obsahuje hlavičku podpisu, kterou může váš endpoint použít k ověření, že datový obsah je pravý a nebyl pozměněn.

​
Hlavička podpisu

x-ah-sig: <signature>
AgencyHandy přidává tuto hlavičku ke každému požadavku webhooku. Extrahujte hodnotu z příchozích požadavků a předejte ji ověřovacímu endpointu.

​
Ověření podpisu webhooku

Odešlete následující požadavek k potvrzení pravosti datového obsahu: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
povinné
ID webhooku, který přijal událost. Najdete jej na stránce detailu webhooku v AgencyHandy.
​
signature
string
povinné
Hodnota hlavičky x-ah-sig z příchozího požadavku webhooku.
​
secret
string
povinné
Tajný klíč webhooku zobrazený na stránce detailu webhooku v AgencyHandy.
​
payload
object
povinné
Nezpracované tělo JSON přijaté z požadavku webhooku AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Odpovědi
​
verification_status
string
SUCCESS pokud je podpis platný. FAILED pokud ověření selže (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Udržujte tajný klíč webhooku v důvěrnosti. Pravidelně jej obměňujte a ihned po obměně aktualizujte svou ověřovací logiku. Nikdy jej nezveřejňujte v klientském kódu ani ve veřejných repozitářích.

​
Důležité poznámky

  • Adresa URL vašeho endpointu musí být veřejně přístupná HTTPS POST URL.
  • Pokud je váš endpoint dočasně nedostupný, zkontrolujte panel historie webhooku v AgencyHandy — jakoukoli minulou událost můžete přímo odtud znovu doručit.
  • Pravidelně monitorujte aktivitu webhooků, abyste odhalili neúspěšná doručení nebo pokusy o neoprávněný přístup.
  • Webhooky, které opakovaně selhávají, mohou být AgencyHandy pozastaveny — sledujte protokoly doručení, abyste problémy zachytili včas.