Veebihaagid

Veebihaagid võimaldavad Ukul lükata muudatused sinu süsteemi kohe, kui need juhtuvad, nii et integratsioon saab reageerida uuele kliendile või muudetud arvele, selle asemel et pidevalt pollida.

Ettevõtte omanikud ja Ettevõtte peakasutajad Elite paketis, kasutades API v3 võtit, millel on Kõik õigus (API nimetab seda admin õiguseks). Vaata Avalik API v3, kuidas võtit luua.

Tellimused luuakse ja kustutatakse API kaudu, mitte Ukus — see on sinu integratsiooni (või sinu nimel tegutseva Zapieri või Make’i) ülesanne. Uku näitab sulle, mis on olemas ja kuidas sellel läheb; vaata allpool Veebihaakide jälgimine.

Iga allolev endpoint on kutsutav ka interaktiivsest sandboxist aadressil app.getuku.com/api/v3/docs, mis on kiireim viis testtellimuse loomiseks ja vastuse uurimiseks.

Üks tellimus on üks sündmus, mis läheb ühele URL-ile. Kolme sündmuse jälgimiseks loo kolm tellimust. Uku ei eemalda dubleerivaid tellimusi, seega kaks tellimust sama sündmuse ja URL-iga saadavad iga sündmuse kaks korda — kontrolli GET /webhooks, enne kui registreerid sama haagi uuesti.

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

Vastus sisaldab allkirjastamise saladust, mis näidatakse ainult sel korral — hoia seda sama hoolikalt kui API võtit ennast. Kui kaotad selle, kutsu POST /webhooks/{id}/rotate-secret uue saamiseks; üleminekuperioodi ei ole, seega uuenda oma vastuvõtjat samal ajal.

Need on sündmused, mida saad tellida (GET /webhooks/events tagastab sama nimekirja):

Sinu URL peab olema avalik aadress — Uku keeldub saatmast privaatsetele, sisemistele või loopback-aadressidele ega järgi kunagi ümbersuunamisi.

Iga saatmine on POST-päring sinu URL-ile. Päringu sisu kannab sündmust ja kirjet ennast, samas kujus, mida vastav GET endpoint tagastab. *.deleted sündmuse puhul sisaldab 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" }
}

Koos sellega 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 seconds>
X-Uku-Retry-Num: <n>          (only on retries)

Kasuta duplikaatide vältimiseks päringu sisu id-d. See püsib samana kõigi selle sündmuse korduskatsete ja kordussaatmiste puhul, nii et vastuvõtja, kes on id-d juba töödelnud, võib selle teistkordse esinemise ohutult ignoreerida.

Iga saatmine on allkirjastatud selle tellimuse enda saladusega, et sinu vastuvõtja saaks tõestada, et päring tuli tõesti Ukust ega ole replay. Allkirjasta ajatempel ja toores päringu sisu, seejärel 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 toorete baitide peal, mille said, enne JSON-i parsimist — uuesti serialiseerimine muudab neid. Üle 5 minuti vanused saatmised tuleks tagasi lükata.

Kui saatmine ebaõnnestub, proovib Uku seda uuesti kindla ajakava järgi ja loobub lõpuks vastuvõtjast, mis jääb katki. Vasta mis tahes 2xx staatusega 10 sekundi jooksul. Kinnita kohalejõudmine kohe ja tegele töötlemisega hiljem — aeglane vastuvõtja loetakse ebaõnnestunuks.

• Korduskatsed. Ebaõnnestunud saatmist proovitakse uuesti 1 minuti, 5 minuti ja 30 minuti pärast — neli katset umbes 36 minuti jooksul, seejärel peatub see.
• Korduskatset ei tehta, kui sinu endpoint tagastab 400, 401, 403, 404, 405, 410 või 422. Need tähendavad, et päring ei õnnestu kunagi, seega Uku loobub kohe. Tagasta 410 Gone, et öelda „see vastuvõtja on kasutuselt kõrvaldatud, lõpeta saatmine.“
• Automaatne väljalülitamine. Pärast 10 järjestikust ebaõnnestumist lülitatakse tellimus välja (is_active läheb valeks ning failure_count, last_failure_at ja disabled_at näitavad põhjust). Paranda oma endpoint, seejärel lülita uuesti sisse päringuga PATCH /webhooks/{id} ja {"is_active": true} — see nullib ka ebaõnnestumiste arvu.
• Ajalugu ja kordussaatmine. GET /webhooks/{id}/deliveries loetleb katsed koos nende vastuse staatusega — üks rida iga katse kohta, seega korduskatsetega sündmus ilmub mitu korda. Uuesti saatmiseks võta selle event_id ja kutsu POST /webhooks/{id}/deliveries/{event_id}/replay. Saatmine, mis on veel korduskatsete käigus, tagastab 409 DELIVERY_IN_PROGRESS — lase sellel enne lõpetada.
• Tempo hoidmine ei ole ebaõnnestumine. Massoperatsiooni käigus — näiteks tuhande kliendi importimisel — jaotab Uku saatmised ajas laiali, selle asemel et need kõik korraga välja saata, seega mõned jõuavad kohale mõne minuti hilinemisega. Tempo hoidmine käivitub tavapärasest liiklusest tunduvalt kõrgemal (600 saatmist minutis, 50 000 päevas ettevõtte kohta), see ei kuluta korduskatseid ega lähe kunagi arvesse automaatse väljalülitamise piiris. Ära aja seda segi oma endpointi maasolekuga.

Uku näitab kõiki veebihaagi tellimusi, mis sinu integratsioonid on loonud, nii et näed ühe pilguga, kas saatmised jõuavad kohale — ilma oma serveri logisid lugemata.

Tee: Seaded & Äpid → Avalik API → Avalik API → Connected webhooks

Nimekiri näitab iga tellimuse kohta veerge: Sündmus, URL, Staatus, Tõrked ja Koostatud kuupäev. Staatus näitab, kus see seisab:

• Active (aktiivne) — saatmised jõuavad kohale.
• Failing (N) (N ebaõnnestumist järjest) — viimased N saatmist järjest ebaõnnestusid. Liigu hiirega ebaõnnestumiste arvu kohale, et näha, millal viimane oli.
• Disabled (välja lülitatud) — kümme ebaõnnestumist järjest, mistõttu Uku lülitas selle välja ega saada enam. Kui see on väljas, ei ole midagi ootel.

Ava rida, et näha selle viimaseid saatmisi koos sündmuse, sinu endpointi tagastatud HTTP staatuse, katse numbri ja ajaga. Ebaõnnestunud saatmisel on nupp Replay; välja lülitatud tellimusel on nupp Re-enable, mis nullib ka selle ebaõnnestumiste arvu.

Veebihaagi tellimus, mis jääb vaikseks, on peaaegu alati Uku poolt välja lülitatud korduvate saatmise ebaõnnestumiste tõttu. Kontrolli seda Seaded & Äpid → Avalik API → Avalik API → Connected webhooks alt. Disabled tähendab, et kümme saatmist järjest ebaõnnestusid ja Uku lülitas selle välja. Paranda vastuvõttev endpoint, seejärel klõpsa Re-enable — see nullib ebaõnnestumiste arvu ja saatmine jätkub. (Sama asja saab teha koodist: GET /webhooks/{id} ja PATCH /webhooks/{id} koos {"is_active": true}.)

Saatmised, mis olid juba korduskatsete käigus, kui tellimus peatati, säilivad — leiad need nimekirjast ja saad kasutada nuppu Replay. Aga sündmused, mis toimusid pärast väljalülitamist, ei salvestatud üldse, seega selle ajavahemiku kohta midagi ei saabu: loe need kirjed API kaudu otse, et järele jõuda.

Uku saadab ainult avalikele internetiaadressidele. localhost URL, sisemine hostinimi, privaatne vahemik nagu 10.x või 192.168.x või miski, mis lahendub üheks neist, lükatakse tellimuse loomisel tagasi. Kohaliku arenduse jaoks pane oma masina ette tunnelduse teenus, et URL oleks avalikult ligipääsetav.

Sama sündmuse kahekordne saamine on oodatud ja ohutult käsitletav: saatmine, mis aegub, võib olla siiski sinuni jõudnud, seega proovib Uku seda uuesti. Iga sündmuse koopia kannab päringu sisus sama id-d — kasuta seda võtmena ja ignoreeri id-d, mida oled juba töödelnud.