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: Webhookit
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Selvitä, miten käytät Webhookeja.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## Yleiskatsaus
|
|
|
|
Webhooks in Twenty complement the API by enabling **real-time notifications** to your own applications when certain events happen in your CRM. Sen sijaan, että kyseltäisit API:a jatkuvasti muutosten varalta, voit asettaa webhookit niin, että Twenty **lähettää** tiedot järjestelmääsi aina, kun tiettyjä tapahtumia tapahtuu (esimerkiksi, kun uusi tietue luodaan tai olemassa oleva tietue päivitetään). Tämä auttaa pitämään ulkoiset järjestelmät synkronoituna Twentyn kanssa välittömästi ja tehokkaasti.
|
|
|
|
Webhookeilla Twenty lähettää HTTP POST -pyynnön määrittelemääsi URL-osoitteeseen, joka sisältää tietoja tapahtumasta. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).
|
|
|
|
## Webhooksin määrittäminen
|
|
|
|
Luo webhook Twentyn sovelluksessa käyttämällä **Rajapinnat & Webhookit** -asetuksia:
|
|
|
|
1. **Siirry Asetuksiin:** Twentyn sovelluksessasi mene **Asetukset → Rajapinnat & Webhookit**.
|
|
2. **Luo Webhook:** Valitse **Webhookit** alta **+ Luo webhook**.
|
|
3. **Syötä URL:** Anna palvelimesi päätepisteen URL, johon haluat Twentyn lähettävän webhook-pyynnöt. Tämä tulee olla julkisesti saatavilla oleva URL, joka voi käsitellä POST-pyyntöjä.
|
|
4. **Tallenna:** Klikkaa **Tallenna** luodaksesi webhookin. Uusi webhook aktivoituu välittömästi.
|
|
|
|
Voit luoda useita webhookkeja, jos haluat lähettää eri tapahtumia eri päätepisteisiin. Jokainen webhook on käytännössä tilaus kaikille asiaankuuluville tapahtumille (tällä hetkellä Twenty lähettää kaikki tapahtumatyypit annettuun URL-osoitteeseen; tiettyjen tapahtumatyyppien suodatus voi olla konfiguroitavissa käyttöliittymässä). If you ever need to remove a webhook, you can delete it from the same settings page (select the webhook and choose delete).
|
|
|
|
## Tapahtumat ja hyötykuormat
|
|
|
|
Kun webhook on määritetty, Twenty lähettää HTTP POST -pyynnön määrittelemääsi URL-osoitteeseen aina, kun käynnistystapahtuma tapahtuu CRM-tiedoissasi. Yleisimmät tapahtumat, jotka käynnistävät webhookit, ovat:
|
|
|
|
- **Tietue luotu:** esim. uusi henkilö on lisätty (`person.created`), uusi yritys on luotu (`company.created`), muistiinpano on luotu (`note.created`), jne.
|
|
- **Tietue päivitetty:** esim. olemassa olevan henkilön tiedot on päivitetty (`person.updated`), yritystietue on muokattu (`company.updated`), jne.
|
|
- **Tietue poistettu:** esim. henkilö tai yritys on poistettu (`person.deleted`, `company.deleted`).
|
|
- **Muut tapahtumat:** Jos sovellettavissa, muut kohdetapahtumat tai mukautetut laukaisut (esimerkiksi, jos tehtävät tai muut objektit päivitetään, käytetään samanlaisia tapahtumatyyppejä kuten `task.created`, `note.updated`, jne.).
|
|
|
|
Webhook POST -pyyntö sisältää JSON-hyötykuorman kehossa. Hyötykuorma sisältää yleensä vähintään kaksi asiaa: tapahtuman tyyppi ja tapahtumaan liittyvät tiedot (usein se tietue, joka luotiin/päivitettiin). Esimerkiksi, webhook äskettäin luodusta henkilöstä saattaa lähettää hyötykuorman, kuten:
|
|
|
|
```
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
|
|
Tässä esimerkissä:
|
|
|
|
- `"event"` osoittaa mitä tapahtui (`person.created`).
|
|
- `"data"` sisältää uuden tietueen tiedot (samat tiedot, jotka saisit pyytämällä kyseistä henkilöä API:n kautta).
|
|
- `"timestamp"` on tapahtuman ajankohta (UTC-ajassa).
|
|
|
|
Päätepisteesi tulee olla valmis vastaanottamaan tällaisia JSON-tietoja POST-pyynnön kautta. Tyypillisesti, JSON puretaan, tarkastellaan `"event"`-tyyppiä ymmärtääksesi mitä tapahtui, ja käytetään sitten `"data"` sen mukaisesti (esim. luodaan uusi kontakti järjestelmääsi tai päivitetään olemassa oleva).
|
|
|
|
**Huom:** On tärkeää vastata **2xx HTTP status** koodilla webhook-päätteen kautta kuittauksena onnistuneesta vastaanotosta. Jos Twenty webhook-lähettäjä ei saa 2xx-vastausta, se saattaa katsoa, että toimitus epäonnistui. (Tulevaisuudessa uudelleenyrityslogiikka saattaa yrittää lähettää epäonnistuneita webhookkeja uudelleen, joten pyri aina palauttamaan 200 OK mahdollisimman nopeasti datan käsittelyn jälkeen.)
|
|
|
|
## Webhook-tarkistus
|
|
|
|
Varmistaaksesi webhook-päätepisteidesi turvallisuuden, Twenty lisää allekirjoituksen `X-Twenty-Webhook-Signature` -otsikkoon.
|
|
|
|
Tämä allekirjoitus on HMAC SHA256 hash pyynnön hyötykuormasta, laskettu käyttämällä webhook-salaisuuttasi.
|
|
|
|
Varmistaaksesi allekirjoituksen, sinun on:
|
|
|
|
1. Yhdistä aikaleima (`X-Twenty-Webhook-Timestamp` -otsikosta), kaksoispiste ja JSON-merkkijono hyötykuormasta
|
|
2. Laske HMAC SHA256 hash käyttämällä webhook-salaisuuttasi avaimena ()
|
|
3. Vertaa tuloksena saatua heksadesimaalista yhteenvetoa allekirjoitusotsikkoon
|
|
|
|
Tässä esimerkki Node.js:ssä:
|
|
|
|
```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");
|
|
``` |