REST hooky pre Make, Zapier a n8n

REST hook je webhook, ktorý si aplikácia vytvorí a zruší sama cez API, takže nikto nemusí vkladať adresy do aplikácie Dakoty. Tak fungujú Make, Zapier a n8n: keď zapnete scenár, prihlásia sa na odber, a keď ho vypnete, odber zrušia. Rovnaké koncové body môžete použiť vo vlastnej integrácii. Doručenie, podpisy a opakovanie fungujú presne ako pri webhookoch. Anglická verzia: REST hooks.

Čo kľúč potrebuje na odber

Kľúč potrebuje oprávnenie webhooks:manage a navyše čítacie oprávnenie každej udalosti, ktorú odoberá, napríklad leads:read pre lead.created. Katalóg udalostí s oprávneniami je na stránke Webhooky. Kľúč, ktorému chýba oprávnenie niektorej udalosti, dostane 403 FORBIDDEN a hook sa nevytvorí.

Prihlásenie cez POST /webhooks

Pošlite adresu target_url s HTTPS (najviac 2048 znakov, verejný server) a udalosti buď ako pole events, alebo v tvare, aký používa Zapier, ako jeden reťazec event. name je voliteľné, bez neho Dakoty pomenuje hook podľa kľúča a prvej udalosti. Odpoveď je 201 s hookom a jeho podpisovým tajomstvom secret.

curl -sS -X POST https://api.dakoty.com/api/v1/public/webhooks \
  -H "Authorization: Bearer $DAKOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://example.com/dakoty/webhook","events":["lead.created","lead.won"],"name":"CRM sync"}'

Odpoveď na vytvorenie a tajný kľúč

Tajný kľúč secret (začína whsec_) sa vráti iba v tejto odpovedi a už sa nezobrazí, preto si ho uložte spolu s id hooku. Odpoveď má hlavičku Cache-Control: no-store. Doručenia nim overujete podľa stránky Overenie podpisu.

{
  "data": {
    "id": "2c7f0f4e-8d1a-4b53-9d1e-5a6b7c8d9e0f",
    "target_url": "https://example.com/dakoty/webhook",
    "events": ["lead.created", "lead.won"],
    "name": "CRM sync",
    "created_at": "2026-10-11T08:30:12Z",
    "secret": "whsec_..."
  }
}

Chyby pri prihlásení na odber

Neznáma udalosť vráti 422 UNKNOWN_EVENT. Adresa, ktorá nezačína https://, vedie na súkromný alebo interný server alebo sa nedá nájsť, vráti 422 WEBHOOK_URL_INVALID alebo WEBHOOK_URL_BLOCKED. Keď organizácia dosiahla najvyšší počet webhookov, dostanete 409 LIMIT_EXCEEDED. Pošlite Idempotency-Key, aby zopakovaná požiadavka hook nezaregistrovala dvakrát, pozri Idempotencia.

Zoznam, detail a zrušenie odberu

GET /webhooks vypíše REST hooky volajúceho kľúča a GET /webhooks/{id} vráti jeden z nich, žiadny nikdy nevracia tajný kľúč. DELETE /webhooks/{id} zruší odber a odpovie 204. Kľúč vidí len hooky, ktoré sám vytvoril, takže hook iného kľúča, ručne vytvorený webhook z aplikácie aj neznáme id odpovedia 404. GET /webhooks/events vypíše dostupné typy udalostí a GET /webhooks/events/{type}/sample vráti vzorovú obálku.

Prihlásenie a odhlásenie v Node.js

Dvojica pomocných funkcií pre aplikáciu, ktorá sleduje zapnutie a vypnutie scenára používateľa. Potrebuje Node.js 18 alebo novší.

const BASE = "https://api.dakoty.com/api/v1/public";
const headers = {
  Authorization: `Bearer ${process.env.DAKOTY_API_KEY}`,
  "Content-Type": "application/json",
};

export async function subscribe(targetUrl, events) {
  const res = await fetch(`${BASE}/webhooks`, {
    method: "POST",
    headers,
    body: JSON.stringify({ target_url: targetUrl, events }),
  });
  const body = await res.json();
  if (res.status !== 201) throw new Error(`${res.status} ${body.error.code}`);
  return body.data; // keep data.id and data.secret
}

export async function unsubscribe(id) {
  const res = await fetch(`${BASE}/webhooks/${id}`, { method: "DELETE", headers });
  if (res.status !== 204 && res.status !== 404) throw new Error(`unsubscribe failed: ${res.status}`);
}

Prihlásenie a odhlásenie v Pythone

Rovnaká dvojica s balíkom requests. Chybu 404 pri mazaní berte ako úspech, lebo hook už mohol zaniknúť.

import os
import requests

BASE = "https://api.dakoty.com/api/v1/public"
HEADERS = {"Authorization": f"Bearer {os.environ['DAKOTY_API_KEY']}"}


def subscribe(target_url, events):
    r = requests.post(f"{BASE}/webhooks", headers=HEADERS, timeout=30,
                      json={"target_url": target_url, "events": events})
    if r.status_code != 201:
        raise RuntimeError(f"{r.status_code} {r.json()['error']['code']}")
    return r.json()["data"]  # keep data["id"] and data["secret"]


def unsubscribe(hook_id):
    r = requests.delete(f"{BASE}/webhooks/{hook_id}", headers=HEADERS, timeout=30)
    if r.status_code not in (204, 404):
        raise RuntimeError(f"unsubscribe failed: {r.status_code}")

Kedy Dakoty REST hook odstráni

REST hooky vlastní aplikácia, preto ich Dakoty nevypína ako ručne vytvorené webhooky. REST hook sa zmaže, keď váš koncový bod odpovie 410 Gone, keď 72 hodín nemal žiadne úspešné doručenie a keď sa zruší API kľúč, ktorý ho vytvoril. Vaša aplikácia má chýbajúci hook brať ako bežnú vec: pri zapnutí scenára zavolajte GET /webhooks/{id} pre uložené id a ak odpovie 404, prihláste odber znova. Ručne vytvorené webhooky ostávajú v aplikácii a popisuje ich článok Ako nastaviť webhook.