Webhooky: udalosti, doručenie a opakovanie
Webhook znamená, že Dakoty zavolá váš server, keď sa niečo stane, takže nemusíte stále dopytovať. Dakoty pošle HTTPS POST s obálkou JSON pre každú udalosť, podpísaný tak, aby ste vedeli overiť pôvod. Táto stránka popisuje zmluvu, podpis rieši stránka Overenie podpisu. Webhooky ručne zakladáte v aplikácii podľa článku Ako nastaviť webhook, nástroje ako Make sa prihlasujú cez REST hooky. Anglická verzia: Webhooks.
Obálka udalosti a jej polia
Section titled “Obálka udalosti a jej polia”Každé doručenie má rovnakú obálku. id je stabilné pre jednu udalosť, opakuje sa pri každom pokuse a rovná sa hlavičke webhook-id, použite ho na deduplikáciu. test je true pri vzorových a testovacích doručeniach. data je záznam presne v tvare, v akom ho vracia zodpovedajúci koncový bod GET.
{ "id": "evt_3f2c0a9e5b1d4c7e8a6f2b1c9d0e3a4b", "type": "lead.created", "timestamp": "2026-10-11T08:30:12Z", "api_version": "2026-10-01", "organization": { "id": "0b5f7c1e-3c52-4d0e-9a53-6f0c1f6a2b11", "slug": "acme" }, "test": false, "data": { "id": "9a1d2c3e-4b5f-4a6b-8c7d-0e1f2a3b4c5d", "name": "Website enquiry", "status": "open", "value": 1200 }}Hlavičky doručenia požiadavky
Section titled “Hlavičky doručenia požiadavky”Každá požiadavka je POST s Content-Type: application/json a user agentom Dakoty-Webhooks/1.0. Okrem podpisu nesie webhook-id, webhook-timestamp (sekundy Unixu, pri každom pokuse nové), X-Dakoty-Event (typ udalosti) a X-Dakoty-Attempt (1 pri prvom pokuse). Podpisové hlavičky webhook-signature a starší X-Dakoty-Signature popisuje stránka Overenie podpisu.
Katalóg udalostí a oprávnenia
Section titled “Katalóg udalostí a oprávnenia”Dakoty ponúka len udalosti, ktoré naozaj odosiela. Kľúč REST hooku potrebuje čítacie oprávnenie každej udalosti, ktorú odoberá. Aktuálny zoznam s názvami a popismi vráti GET /webhooks/events (oprávnenie webhooks:manage).
| Skupina | Udalosti | Oprávnenie |
|---|---|---|
| Leady | lead.created, lead.updated, lead.archived, lead.stage_changed, lead.won, lead.lost | leads:read |
| Firmy a kontakty | company.created, company.updated, contact.created, contact.updated | companies:read |
| Klienti | client.created, client.updated | clients:read |
| Aktivity | activity.created, activity.completed, activity.cancelled | activities:read |
| Úlohy | task.created, task.moved, task.completed, task.overdue | tasks:read |
| Faktúry a ponuky | invoice.created, invoice.paid, invoice.overdue, quote.accepted, quote.rejected | invoices:read |
| Rezervácie | booking.created, booking.confirmed, booking.cancelled, booking.completed, booking.no_show | bookings:read |
| Produkty | product.created, product.updated | products:read |
| Objednávky | order.created, order.confirmed, order.paid, order.picking, order.packed, order.ready_for_pickup, order.shipped, order.delivered, order.cancelled, order.returned | orders:read |
| Platby objednávok | order.payment_pending, order.payment_paid, order.payment_refunded, order.payment_failed | orders:read |
Vzorová udalosť na mapovanie
Section titled “Vzorová udalosť na mapovanie”Ak si chcete postaviť mapovanie skôr, než vznikne prvá skutočná udalosť, vyžiadajte si statickú vzorovú obálku s test: true. Odpoveď je pole s jednou obálkou. Vyžaduje kľúč s oprávnením webhooks:manage.
curl -sS https://api.dakoty.com/api/v1/public/webhooks/events/lead.created/sample \ -H "Authorization: Bearer $DAKOTY_API_KEY"Čo je úspešné doručenie
Section titled “Čo je úspešné doručenie”Odpovedzte ľubovoľným stavom 2xx do 10 sekúnd. Všetko ostatné je neúspešný pokus: stav mimo 2xx, vypršanie času, chyba spojenia alebo TLS, alebo presmerovanie (Dakoty presmerovania nenasleduje, preto zaregistrujte konečnú adresu). Cieľ musí byť adresa https:// na verejnom serveri, súkromné a interné adresy sa odmietnu. Najprv potvrďte a spracujte až potom, pomalý obslužný kód vyprší a spustí opakovanie.
Rozvrh opakovania neúspešných doručení
Section titled “Rozvrh opakovania neúspešných doručení”Neúspešná správa sa skúša najviac deväťkrát: prvý pokus je okamžitý a ďalšie nasledujú po čase z tabuľky, čo rozloží pokusy na približne 2,3 dňa. Ak váš server odpovie 429 alebo 503 s hlavičkou Retry-After, ďalší pokus počká aspoň tak dlho, najviac 24 hodín.
| Pokus | Čakanie po predchádzajúcom pokuse |
|---|---|
| 1 | hneď |
| 2 | 5 sekúnd |
| 3 | 5 minút |
| 4 | 30 minút |
| 5 | 2 hodiny |
| 6 | 5 hodín |
| 7 | 10 hodín |
| 8 | 14 hodín |
| 9 | 24 hodín |
Doručenie aspoň raz
Section titled “Doručenie aspoň raz”Dakoty môže tú istú udalosť doručiť aj viackrát, napríklad keď váš server udalosť spracoval, ale odpoveď sa stratila. Po opakovaniach môžu udalosti prísť aj v inom poradí. Obslužný kód urobte idempotentný: ukladajte id obálky každej spracovanej udalosti a opakovania preskočte, a ak záleží na poradí, použite timestamp alebo záznam znova načítajte. Každý pokus používa rovnaké webhook-id a rovnaké telo.
Automatické vypnutie po výpadku
Section titled “Automatické vypnutie po výpadku”Ak webhook 24 hodín nič nedoručí, Dakoty pošle e-mail ľuďom určeným na upozornenie. Po 72 hodinách bez úspešného doručenia sa webhook vypne automaticky a nové udalosti sa až 30 dní držia (najviac 1 000 na webhook), aby sa nestratili. Webhooky vytvorené aplikáciou, napríklad Make, sa nevypínajú, ale mažú, pozri REST hooky. Rovnaké stavy v aplikácii popisuje článok Prečo webhook zlyháva a čo s tým.
Odpoveď 410 Gone
Section titled “Odpoveď 410 Gone”Vráťte 410 Gone zo svojho koncového bodu, ak sa chcete odhlásiť natrvalo. Dakoty okamžite prestane doručovať a nič neopakuje: ručne vytvorený webhook sa vypne s dôvodom „gone“ a REST hook sa zmaže. Použite to, keď sa koncový bod ruší navždy, a pri dočasnom výpadku, z ktorého sa zotavíte, vráťte radšej stav 5xx.