Veebihaagid

Selle artikli lõpuks tead, millisele mootorile ehitada, kuidas selle saadetis välja näeb ja kuidas seda turvaliselt käsitleda.

Veebihaake saavad hallata Ettevõtte omanikud ja Ettevõtte peakasutajad. Ettevõtte kasutajad ei saa.

Tee: Seaded & Äpid → Avalik API

Vajad ka võtit selle mootori jaoks, mida kasutad. v3 veebihaakide jaoks on see Kõik õigusega API v3 võti (vaata Avalik API v3). v1.0 veebihaakide jaoks on see v1.0 võtmepaar (vaata Avalik API v1.0). Need ei ole omavahel vahetatavad.

Mõlemad mootorid vajavad Elite paketti, aga jõustavad seda erinevalt. Avalik API äpp on Elite’i äpp ja just seal mõlemat liiki võtmed luuakse. Ilma Elite’ita sa mandaati üldse ei saa. API v3 kontrollib paketti ka igal päringul. Kui ettevõte ei ole enam Elite’is, vastab see 403 PLAN_UPGRADE_REQUIRED. v1.0 lõpp-punktid seda ei kontrolli, seega Elite’i ajal väljastatud võtmepaar töötab edasi.

Tellimused luuakse alati API kaudu, mitte Uku liideses. Seda teeb sinu integratsioon või Zapier või Make sinu eest.

Ehita API v3 peale. v3 mootor ulatub Ukus palju kaugemale ja allkirjastab iga tellimuse omaenda saladusega. See kordab ebaõnnestunud saatmist ja peab ajalugu, mida saad vaadata ja uuesti saata. Kasuta v1.0 ainult selleks, et hoida töös integratsiooni, mis sul juba on.

Uku käitab kahte mootorit kõrvuti. Neil on ühine tellimuste hoidla, aga eri vormingud, ja kumbki saadab ainult omaenda tellimustele. Nii ei saa v1.0 tellija kunagi v3 kujul keha.

Rida Käivitub kirjetel, mis on loodud on see, mis inimesi üllatab. Kaks mootorit kuulavad peaaegu vastandlikes kohtades. Nende vahel liikumine muudab seda, milliste kirjete kohta sa kuuled, mitte ainult sõnumi kuju — vaata Üleminek API v1.0 pealt API v3 peale.

v3 kataloog ulatub Ukus kaugemale kui v1.0 kaks käivitajat: kliendid, kontaktid, ülesanded, projektid, arved ja ajakirjed, igaüks loodud, muudetud ja kustutatud sündmustega.

Kolm asja, mida nimed ise ei ütle. Ülesande muudatused katavad staatuse, vastutaja ja kuupäeva muutused, seega piisab ühest tellimusest, et ülesande elu jälgida. Arve kustutamise sündmust ei ole, sest API ei ava ühtki viisi arve kustutamiseks. Ja ajakirjed käivituvad ainult loomisel.

GET /webhooks/events tagastab praeguse kataloogi, seega loe see API-st, selle asemel et loendit oma koodi kopeerida.

Kõik need käivituvad ainult API v3 kaudu tehtud kirjutamistel, mitte Uku veebirakenduses tehtud töö peale.

Üks v3 tellimus on üks sündmus, mis läheb ühele URL-ile. Kolme sündmuse kuulamine tähendab kolme tellimuse loomist. Uku neid ei ühenda: kaks sama sündmuse ja URL-iga tellimust saadavad kõik kaks korda, seega kontrolli GET /webhooks enne sama haagi uuesti registreerimist.

1. Loo API v3 võti õigusega Kõik. Iga v3 veebihaagi lõpp-punkt vajab seda — API dokumentatsioonis admin õigus. Lugemine või Muuda võti ei saa isegi tellimusi loetleda.

2. Saada tellimuse päring, nimetades ühe sündmuse ja URL-i, kuhu see peaks jõudma:

   curl -X POST https://app.getuku.com/api/v3/webhooks \
     -H "X-Uku-Company: sinu-ettevotte-uuid" \
     -H "X-API-Key: uku_live_..." \
     -H "Content-Type: application/json" \
     -d '{"webhook": "client.created", "url": "https://example.com/hooks/uku"}'

3. Salvesta allkirja saladus, mis vastusega tuleb. Uku näitab seda ainult sel korral, seega hoia seda sama hoolikalt kui API võtit.

4. Seo oma vastuvõtja väljad päringu GET /webhooks/example järgi, mis tagastab saadetise päris kujul. Sellest sidumine on parem kui oodata päris sündmust, et näha, milline see välja näeb.

Kui saladus kaob, loob POST /webhooks/{id}/rotate-secret uue. Vana saladus lakkab töötamast samal hetkel, kattuvat perioodi ei ole, seega uuenda samal ajal ka oma vastuvõtjat.

v3 mootor on sinu URL-i suhtes rangem kui v1.0. See kontrollib hosti tellimisel, kontrollib seda uuesti saatmise hetkel, ühendub täpselt selle aadressiga, mille kontrollis, ja ümbersuunamisi ei järgi. URL, mis laheneb privaatsele, loopback-, link-local- või reserveeritud aadressile, lükatakse tellimisel tagasi veaga 400, mitte ei kuku vaikselt läbi hiljem.

v3 saadetis on POST, mille keha mähib kirje ümbrikusse, mis kannab sündmuse nime ja aega. *.deleted sündmuse puhul hoiab data ainult id-d.

{
  "id": "8f1c2a4e-3b7d-4c21-9f0e-2a6b5d8c1e73",
  "event": "client.created",
  "occurred_at": "2026-07-14T10:15:33+00:00",
  "data": { "id": 123, "name": "Apple Ltd" }
}

Sellega koos tulevad need päised:

X-Uku-Event: client.created
X-Uku-Delivery-Id: 8f1c2a4e-3b7d-4c21-9f0e-2a6b5d8c1e73
X-Uku-Webhook-Id: 42
X-Uku-Signature: sha256=<hex>
X-Uku-Timestamp: <unix sekundid>
X-Uku-Retry-Num: <n>          (ainult korduskatsetel)

Päring esitleb end ka kui User-Agent: Uku-Webhooks/3.0. Kui sinu vastuvõtja on veebirakenduse tulemüüri taga, on see string, mis lubada.

Eemalda duplikaadid keha id järgi. See jääb samaks iga korduskatse ja kordussaatmise juures. Vastuvõtja, kes on id juba käsitlenud, võib selle teisel korral ohutult vahele jätta. occurred_at on sündmuse enda aeg, mitte saatmise aeg. Pool tundi hiljem korratud saadetis teatab endiselt, millal muudatus tegelikult juhtus.

Iga v3 saadetis allkirjastatakse selle tellimuse omaenda saladusega, nii et sinu vastuvõtja saab tõestada, et päring tuli Ukust just sinu tellimuse jaoks. Üks jagatud võti seda kunagi tõestada ei saa. Allkirjasta ajatempel ja toorkeha ning võrdle:

import hmac, hashlib, time

def verify(secret, raw_body, signature, timestamp, tolerance=300):
    if abs(int(time.time()) - int(timestamp)) > tolerance:
        return False                      # liiga vana — lükka tagasi
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Arvuta see toorbaitide järgi, mille said, enne JSON-i parsimist, sest uuesti sarjastamine muudab neid. Kontrolli lisaks allkirjale ka ajatemplit: kehtiv allkiri jääb kehtima igavesti ja ainult kellakontroll takistab püütud saadetise sulle tagasi mängimist. Lükka tagasi saadetised, mis on üle viie minuti vanad.

Uku ei saada v3 saadetist, mida ta allkirjastada ei saa. Kui tellimusel mingil põhjusel saladust ei ole, keeldutakse saatmisest ja see logitakse, selle asemel et saata allkirjata.

Ebaõnnestunud v3 saadetist korratakse kindla redeli järgi ja Uku annab lõpuks alla vastuvõtja suhtes, mis katki jääb. Vasta mis tahes 2xx staatusega 10 sekundi jooksul. Kinnita esmalt kättesaamine ja töötle pärast, sest aeglane vastuvõtja loeb ebaõnnestunuks.

• Korduskatsed. Ebaõnnestunud saadetist korratakse 1 minuti, 5 minuti ja 30 minuti pärast — neli katset umbes 36 minuti jooksul, siis see lõpeb.
• Korduskatset ei tehta, kui sinu lõpp-punkt tagastab 400, 401, 403, 404, 405, 410 või 422. Iga neist tähendab, et päring ei õnnestu kunagi, seega Uku annab kohe alla. Tagasta 410 Gone, et öelda „see vastuvõtja on pensionil, lõpeta saatmine”.
• Automaatne väljalülitamine. Pärast 10 järjestikust ebaõnnestumist lülitatakse tellimus välja (is_active läheb vääraks ning failure_count, last_failure_at ja disabled_at ütlevad, miks). Uku saadab e-kirja ja teavituse Ettevõtte omanikule ja tellimuse loojale, nii et saad teada ilma küsimata. Paranda lõpp-punkt ja lülita siis uuesti sisse päringuga PATCH /webhooks/{id} ja kehaga {"is_active": true} — see nullib ka ebaõnnestumiste loenduri.
• Ajalugu ja kordussaatmine. GET /webhooks/{id}/deliveries loetleb katsed koos vastuse staatusega — üks rida katse kohta, nii et korratud sündmus ilmub mitu korda. Iga rida hoiab ka seda, mida sinu lõpp-punkt tagasi saatis, kuni teatud mahuni. Nii saad lugeda oma vastuvõtja tagastatud vea ilma omaenda logisid avamata. Uuesti saatmiseks võta selle event_id ja kutsu POST /webhooks/{id}/deliveries/{event_id}/replay. Saadetis, mis alles korduskatseid teeb, tagastab 409 DELIVERY_IN_PROGRESS, seega lase sel lõpuni jõuda.
• Tempo hoidmine ei ole ebaõnnestumine. Hulgitoimingu ajal, näiteks tuhande kliendi importimisel, jaotab Uku saatmised ajas laiali, selle asemel et kõik korraga välja lasta. Osa jõuab kohale mõni minut hiljem. Tempo hoidmisel saadetis lükkub edasi, mitte ei ebaõnnestu. Tempo hoidmine algab alles tavaliikluse mahust palju kõrgemal, see ei kuluta korduskatseid ega lähe kunagi automaatse väljalülitamise arvele. Ära pea seda oma lõpp-punkti seisakuks. Saadetis, mis jääb liiga kauaks ootele, pargitakse staatusega „throttled for too long”, mitte ei visata ära. Saad selle ikka uuesti saata.

Kasuta seda mootorit ainult selleks, et hoida töös olemasolevat integratsiooni. Kõige uue jaoks telli API v3-ga.

v1.0 käivitaja on kitsas: Uku veebirakenduses loodud klient või kontakt, sündmuste client_added ja contact_added kaudu. Sellel mootoril ei ole muutmise ega kustutamise käivitajat ja miski muu seda ei käivita. Ükski muu allikas v1.0 saadetist ei tekita: ei API v1.0 enda kaudu loodud kirje, ega API v3, import, automaatika, ajastatud töö või Kliendiportaal. Nii ei kuule integratsioon, mis Ukusse kirjutab, kunagi omaenda kirjutamisi tagasi.

Autendi nii, nagu ülejäänud API v1.0 töötab: vaheta oma võtmepaar JWT tokeni vastu ja saada siis see token. Token kehtib ainult kümme minutit, seega skript, mis tellib ja jääb siis vait, peab enne järgmist päringut uuesti sisse logima.

curl -X POST https://app.getuku.com/api/v1.0/webhooks/subscription \
  -H "Authorization: Bearer <sinu-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"webhook": "client_added", "url": "https://example.com/hooks/uku"}'

Saatmise lõpetamiseks kasuta DELETE /api/v1.0/webhooks/subscription/{id}. Tellimuse loomine ja kustutamine on kogu haldusvõimalus: peatamist, muutmist ega varasemate saatmiste vaatamist ei ole.

v1.0 saadetis on POST, mille keha on loodud kirje ise, lameda kujuga, ilma ümbrikuta. Kliendi puhul on see sama kuju, mille tagastab v1.0 GET /clients lõpp-punkt. Kontakti puhul on see kontaktikirje, kus klient, kellele see kuulub, on väljal client_id. created_at ja updated_at tulevad kaasa ISO-kujul. Allolev näide on lühendatud — päris kliendikirje kannab palju rohkem välju.

{
  "id": 123,
  "name": "Apple Ltd",
  "reg_code": "12345678",
  "created_at": "2026-08-13T09:41:07Z",
  "updated_at": "2026-08-13T09:41:07Z"
}

Sellega tuleb kaasa ainult kaks päist: Content-Type ja — kui platvormi allkirjavõti on seadistatud — X-Webhook-Signature, mis on toorkeha HMAC-SHA256 räsi. Sellel mootoril ei ole sündmuse nime päist, seega üks URL, mis saab nii client_added kui ka contact_added, ei suuda neid ilma keha uurimata eristada. Anna igale v1.0 sündmusele oma URL ja probleem kaob.

v1.0 allkirjavõti on üks Uku-ülene väärtus, mitte tellimuse kohta väljastatud, ja Uku liides seda kusagil ei näita. Nii ei saa sa sellel mootoril allkirja kontrolli ise üles seada. Tellimusepõhine allkirjastamine on v3 võimalus. v1.0-s on turvalisem muster kohelda saadetist teatena, et midagi loodi, ja lugeda kirje enne tegutsemist API-st tagasi. Mõistlik lisakontroll on panna oma vastuvõtu-URL-i teekonda äraarvamatu märgis.

Sinu URL peab olema avalik internetiaadress ja sellel mootoril toimub kontroll saatmise hetkel, mitte tellimisel. Privaatne või loopback-aadress võetakse tellimusena vastu ja kukub siis vaikselt igal saatmisel läbi. Vaata Miks Uku ütleb, et mu veebihaagi URL on vigane?.

Ebaõnnestunud v1.0 saadetist korratakse mõned korrad, sekundite vahega, ja siis loobutakse. Vasta kiiresti: ajalimiit on lühike ja aeglane lõpp-punkt loeb ebaõnnestunuks.

Miski sellest ei ole sulle hiljem nähtav. See mootor ei salvesta saatmiste ajalugu, seega ebaõnnestunud saadetis ei jäta rida, mida saaksid vaadata või uuesti saata. Surnud lõpp-punkti suunav tellimus jääb lõputult proovima, selle asemel et end välja lülitada. Kui v1.0 veebihaak on sinu protsessi jaoks oluline, võrdle perioodiliselt kirjeid API-st, selle asemel et loota ainult saatmisele.

Olemasoleva veebihaagi integratsiooni v3 peale kolimine on vastuvõtja ümberehitamine, mitte seade, mida ümber lülitad. Kolme muudatust on kerge mitte märgata, seega planeeri need enne alustamist.

Mõlema mootori korraga kasutamine saadab kaks korda. v1.0 tellimus ja v3 tellimus, mis katavad sama asja, käivituvad mõlemad. Nii tekitab üks kliendi loomine kaks saadetist kahes eri kujus. Uue vastuvõtja kontrollimise ajal on see kasulik meelega kattuvus ja kohale jäetuna viga. Kustuta v1.0 tellimus päringuga DELETE /api/v1.0/webhooks/subscription/{id}, kui v3 saadetised jõuavad õigesti kohale.

Sündmuste nimed muutuvad. client_added muutub client.created-ks ja contact_added muutub contact.created-ks. Kahe sõnavara vahel tõlkekihti ei ole ja v1.0 tellimust ei kirjutata kunagi v3 tellimuseks ümber.

Muutub see, mille kohta sa kuuled, mitte ainult see, kuidas see välja näeb. v1.0 käivitub ainult Uku veebirakenduses loodud kirjetel. v3 käivitub ainult API v3 kaudu tehtud kirjutamistel. See hõlmab ka kõike, mis on ehitatud Uku MCP serverile, sest see kutsub sama API-t. Nii ei näe büroo, kelle kliendid sisestab personal brauseris, nende kohta ühtki v3 saadetist. Integratsioon, mis loob kliente API kaudu ja pole seetõttu kunagi tekitanud ühtki v1.0 saadetist, hakkab v3 omi tekitama esimesest kirjutamisest. Selgita enne välja, kumb neist sinu bürood kirjeldab, kui eeldad, et kolimine on üks-ühele.

Kaks väiksemat erinevust tasub samal ajal sisse ehitada. v3 saadab päise X-Uku-Event, nii et üks URL saab teenindada mitut sündmust. Ja see esitleb end kui User-Agent: Uku-Webhooks/3.0, mille sinu vastuvõtja ees olev tulemüür võib vajada lubatud loendisse.

Uku veebihaakide jälgimise vaade loetleb ainult API v3 tellimusi. v1.0 tellimus ei ilmu sinna kunagi, olgu see kui tahes hästi saatmas. Tühi vaade ei ole seega tõend, et midagi on seisma jäänud.

Tee: Seaded & Äpid → Avalik API → Avalik API → Ühendatud webhookid

Iga rida annab tellimuse Sündmus, URL, Staatus, Tõrked ja Koostatud kuupäeva. Aktiivne tähendab, et saadetised jõuavad kohale. Tõrkuv (N) tähendab, et viimased N järjest ebaõnnestusid, ja loenduri kohal hõljudes näed, millal viimane oli. Keelatud tähendab, et tellimus ei ole aktiivne — kas sa peatasid selle või lülitas kümme järjestikust ebaõnnestumist selle välja. Tõrked loendur ütleb, kumb. Igal real on Peata, Lülita uuesti sisse või Kustuta tegevus. Rea avamine näitab hiljutisi saatmisi koos sinu lõpp-punkti tagastatud staatusega, mitmes katse see oli, ja Saada uuesti nupuga ebaõnnestunutel.

Ühendatud webhookid vaade loetleb ainult API v3 tellimusi. Veebihaak, mille seadistasid varem Zapieri, Make’i või oma koodi kaudu, on suure tõenäosusega v1.0 tellimus ja need sinna kunagi ei ilmu. Selle kontrollimiseks kutsu GET /api/v1.0/webhooks/subscription, mis loetleb selle, mis päriselt olemas on.

API v3-s on vait jäänud tellimus tavaliselt automaatselt välja lülitatud. Ava Seaded & Äpid → Avalik API → Avalik API → Ühendatud webhookid, vaata Tõrked loendurit Keelatud staatuse kõrval, paranda lõpp-punkt ja klõpsa siis Lülita uuesti sisse. Juba salvestatud saadetisi saab uuesti saata. Sündmusi, mis käivitusid ajal, mil see oli väljas, ei salvestatud ega saagi salvestada, seega loe need kirjed järelejõudmiseks API-st.

API v1.0-s ei lülitata tellimust kunagi automaatselt välja, seega vaikus tähendab üht kolmest. Keegi ei ole pärast su viimast vaatamist Uku veebirakenduses klienti ega kontakti loonud. Kirje loodi kohas, mida v1.0 mootor ei jälgi. Või sinu lõpp-punkt ebaõnnestub. See mootor ei pea saatmiste ajalugu, seega Ukus ei ole midagi uurida. Vaata oma vastuvõtja logisid, kontrolli, et lõpp-punkt vastab POST-päringule kiiresti, ja kontrolli päringuga GET /api/v1.0/webhooks/subscription, et tellimus on veel alles.

Uku saadab mõlemal mootoril ainult avalikele internetiaadressidele. localhost URL, sisemine hostinimi, privaatne vahemik nagu 10.x või 192.168.x või miski, mis nendeni laheneb, jääb saatmata. API v3 lükkab sellise URL-i tellimuse loomisel kohe tagasi veaga 400. API v1.0 võtab selle vastu ja kukub siis vaikselt igal saatmisel läbi, mis näeb välja täpselt nagu seisakus lõpp-punkt. Kohalikuks arenduseks pane oma masina ette tunnelteenus, nii et URL oleks avalikult kättesaadav.

Sama sündmuse kaks korda saamine on ootuspärane ja ohutu käsitleda: saadetis, mille ajalimiit sai täis, võis sinuni siiski jõuda, seega Uku kordab seda. API v3-s kannab iga sündmuse koopia kehas sama id-d — kasuta seda võtmena ja jäta juba käsitletud id vahele. API v1.0-s sellist id-d ei ole, seega eemalda duplikaadid kirje enda id ja created_at järgi. Kui käitad ülemineku ajal mõlemat mootorit, on duplikaat pigem üks saadetis kummastki mootorist kui korduskatse.

Ei. Kaks mootorit hoitakse andmebaasis lahus ja kumbki saadab ainult omaenda tellimustele. v1.0 kaudu loodud tellimus saab edasi lameda v1.0 keha ja päise X-Webhook-Signature. Kui soovid rikkalikumat v3 sündmuste komplekti, loo uus v3 tellimus — vana ei migreerita ega kirjutata ümber. Kuni mõlemad on olemas, saad iga sündmuse kaks korda, millega tuleb arvestada.