8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
5.4 KiB
Plaintext
87 lines
5.4 KiB
Plaintext
---
|
|
title: Webhooky
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Zjistěte, jak používat naše Webhooky.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## 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:
|
|
|
|
```javascript
|
|
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");
|
|
``` |