Přejít na hlavní obsah
Header

​
Přehled

Webhooky v Twenty doplňují API tím, že umožňují oznámení v reálném čase do vašich aplikací, když se události stanou ve vašem CRM. Místo neustálého dotazování API na změny můžete nastavit webhooky, které umožní aplikaci Twenty odesílat data do vašeho systému vždy, když dojde ke specifickým událostem (například když je vytvořen nový záznam nebo aktualizován stávající). To pomůže udržet externí systémy synchronizované s Twenty okamžitě a efektivně. S využitím webhooků Twenty odešle požadavek HTTP POST na URL, které určíte, a to včetně podrobností o události. Můžete pak tato data zpracovat ve vaší aplikaci (např. pro aktualizaci vaší externí databáze, spuštění pracovních postupů nebo odesílání upozornění).

​
Nastavení Webhooku

Chcete-li vytvořit webhook v Twenty, použijte nastavení API & Webhooks ve vaší aplikaci Twenty:
  1. Přejděte do Nastavení: V aplikaci Twenty přejděte do Nastavení → API & Webhooks.
  2. Vytvořit Webhook: Pod Webhooky klikněte na + Vytvořit webhook.
  3. Zadejte URL: Poskytněte koncovou URL na vašem serveru, kam chcete, aby Twenty zasílalo požadavky webhooků. Toto by měla být veřejně přístupná URL, která zvládne POST požadavky.
  4. Uložit: Klikněte na Uložit pro vytvoření webhooku. Nový webhook bude aktivní okamžitě.
Můžete vytvořit více webhooků, pokud potřebujete odesílat různé události na různé koncové body. Každý webhook je v podstatě předplatné pro všechny relevantní události (v současné době Twenty odesílá všechny typy událostí na danou URL; filtrování specifických typů událostí může být konfigurovatelné v uživatelském prostředí). Pokud někdy potřebujete odstranit webhook, můžete jej odstranit ze stejné stránky nastavení (vyberte webhook a zvolte smazání).

​
Události a Zatížení

Jakmile je webhook nastaven, Twenty pošle HTTP POST požadavek na vámi specifikovanou URL vždy, když dojde ke spouštěcí události ve vašich CRM datech. Běžné události, které spouští webhooky, zahrnují:
  • Záznam Vytvořen: např. je přidána nová osoba (person.created), vytvořena nová firma (company.created), nebo vytvořen záznam (note.created), atd.
  • Záznam Aktualizován: např. jsou aktualizovány informace stávající osoby (person.updated), editován záznam firmy (company.updated), atd.
  • Záznam Smazán: např. osoba nebo firma je smazána (person.deleted, company.deleted).
  • Další Události: pokud je to relevantní, jiné události objektů nebo vlastní spouštěče (například pokud jsou úkoly nebo jiné objekty aktualizovány, budou použity podobné typy událostí jako task.created, note.updated, atd.).
Webhook POST požadavek obsahuje JSON payload ve svém těle. Payload obecně zahrnuje alespoň dvě věci: typ události a údaje vztahující se k této události (často záznam, který byl vytvořen/aktualizován). Například webhook pro nově vytvořenou osobu může odeslat payload jako: 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
V tomto příkladu:
  • "událost" specifikuje, co se stalo (person.created).
  • "data" obsahuje detaily nového záznamu (stejné informace, které byste získali, pokud byste požádali o danou osobu přes API).
  • "časová značka" je kdy daná událost nastala (v UTC).
Vaše koncová URL by měla být připravena přijímat taková JSON data přes POST. Obvykle budete parsovat JSON, podívat se na typ "událost", abyste pochopili, co se stalo, a pak podle potřeby použít "data" (např. vytvořit nový kontakt ve vašem systému nebo aktualizovat stávající). Poznámka: Je důležité reagovat z vašeho webhookového koncového bodu s 2xx HTTP statusem, aby bylo potvrzeno úspěšné přijetí. Pokud Twenty webhook sender nedostane odpověď 2xx, může považovat doručení za neúspěšné. (V budoucnu může logika pokusů o nové odeslání pokusit se znovu odeslat neúspěšné webhooky, proto se vždy snažte vrátit 200 OK co nejrychleji po zpracování dat.)

​
Ověření Webhooku

Pro zajištění bezpečnosti vašich webhookových koncových bodů obsahuje Twenty podpis v hlavičce X-Twenty-Webhook-Signature. Tento podpis je HMAC SHA256 hash payloadu požadavku, vypočítaný pomocí vašeho webhookového tajemství. Pro ověření podpisu budete potřebovat:
  1. Spojte časovou značku (z hlavičky X-Twenty-Webhook-Timestamp), dvojtečku a JSON řetězec payloadu
  2. Vypočítejte HMAC SHA256 hash pomocí vašeho webhookového tajemství jako klíče
  3. Porovnejte vzniklý hex digest s hlavičkou podpisu
Zde je příklad v Node.js: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");