Webhook Zauwaguj: uwagi do Make, Zapiera i n8n

Zdarzenia

Webhook ustawiasz w projekcie: Integracje → Webhook, adres i (opcjonalnie) klucz do podpisu. Zauwaguj od razu wysyła zdarzenie testowe — jeśli adres nie odpowie, połączenie się nie zapisze.

Każde żądanie to POST z Content-Type: application/json i nagłówkami X-Zauwaguj-Zdarzenie (nazwa zdarzenia) oraz X-Zauwaguj-Podpis. W treści zawsze są pola zdarzenie i wyslano (data ISO 8601).

Treść zdarzenia uwaga.nowa

{
  "zdarzenie": "uwaga.nowa",
  "wyslano": "2026-10-30T10:14:05+01:00",
  "uwaga": {
    "nr": 12,
    "tytul": "[UWAGA 12] Zamieńcie zdjęcie w nagłówku na wersję z ludźmi…",
    "tekst": "Zamieńcie zdjęcie w nagłówku na wersję z ludźmi przy ladzie.",
    "autor": "Anna Nowak",
    "email": "anna@piekarnia.pl",
    "strona": "https://dev.piekarnia.pl/o-nas",
    "link": "https://dev.piekarnia.pl/o-nas#uwaga-12",
    "link_publiczny": "https://dev.piekarnia.pl/o-nas#uwaga-12",
    "selektor": "header .hero img",
    "przegladarka": "Safari, iPhone",
    "ekran": "390×844",
    "panel": "https://zauwaguj.pl/panel/uwagi/345",
    "utworzono": "2026-10-30T10:14:02+01:00",
    "pliki": [
      { "nazwa": "zrzut.jpg", "typ": "image/jpeg", "rozmiar": 184233, "zrzut": true }
    ],
    "tekst_md": "Zamieńcie zdjęcie…\n\n[Pokaż na stronie →](https://…)\n\n- **Strona:** …"
  }
}

• link otwiera stronę z tą pinezką. W projekcie „Tylko osoby z linkiem” prowadzi przez Zauwaguj, żeby zespół zobaczył widget; link_publiczny to zawsze zwykły adres strony z #uwaga-12, który możesz pokazać klientowi.
• pliki to lista załączników (nazwa, typ, rozmiar w bajtach, czy to zrzut ekranu) — same pliki zobaczysz w panelu pod linkiem panel.
• tekst_md to gotowy opis zadania w Markdownie: treść, link do pinezki i lista danych. Wystarczy wkleić go do opisu karty.
• selektor i ekran mogą być puste (null) — np. przy uwadze do grafiki.

Treść zdarzenia uwaga.odpowiedz

{
  "zdarzenie": "uwaga.odpowiedz",
  "wyslano": "2026-10-30T11:02:40+01:00",
  "uwaga": { "nr": 12, "link": "…#uwaga-12", "link_publiczny": "…#uwaga-12", "id_zewnetrzne": "RT-4521" },
  "odpowiedz": { "autor": "Piotr z zespołu", "email": "piotr@agencja.pl", "zespol": true,
                 "tekst": "Podmienione, sprawdź proszę na telefonie.", "kiedy": "2026-10-30T11:02:38+01:00" }
}

id_zewnetrzne to identyfikator, który Twój system oddał przy uwaga.nowa. Jeśli odpowiesz na uwaga.nowa JSON-em {"id": "RT-4521", "url": "https://…"}, Zauwaguj zapamięta id, a przy uwadze w panelu pokaże link url do Twojego zadania. Bez tego id_zewnetrzne ma postać uwaga-12.

Podpis i weryfikacja

Nagłówek X-Zauwaguj-Podpis ma postać sha256=…: to HMAC SHA-256 z surowej treści żądania, liczony Twoim kluczem. Klucz widać przy webhooku w projekcie; jeśli go nie podasz, Zauwaguj wygeneruje losowy. Porównuj podpis z surowymi bajtami treści, zanim zdekodujesz JSON.

PHP:

$tresc = file_get_contents('php://input');
$podpis = 'sha256=' . hash_hmac('sha256', $tresc, $klucz);
if (!hash_equals($podpis, $_SERVER['HTTP_X_ZAUWAGUJ_PODPIS'] ?? '')) {
    http_response_code(401);
    exit;
}
$zdarzenie = json_decode($tresc, true);

Node.js:

const crypto = require('node:crypto');
// tresc: Buffer z surową treścią żądania (np. express.raw({ type: 'application/json' }))
const oczekiwany = 'sha256=' + crypto.createHmac('sha256', klucz).update(tresc).digest('hex');
const otrzymany = req.get('X-Zauwaguj-Podpis') || '';
const zgodny = otrzymany.length === oczekiwany.length &&
  crypto.timingSafeEqual(Buffer.from(otrzymany), Buffer.from(oczekiwany));

Make, Zapier i n8n

• Make: moduł Webhooks → Custom webhook, skopiuj adres do Zauwaguj. Zdarzenie testowe pozwoli Make odczytać strukturę danych.
• Zapier: trigger Webhooks by Zapier → Catch Hook, adres wklej w Zauwaguj, potem w Zapierze Test trigger.
• n8n: węzeł Webhook z metodą POST; do testu użyj adresu testowego, a w działającym workflow — produkcyjnego.

Dalej rozdzielasz zdarzenia po polu zdarzenie: uwaga.nowa zakłada kartę albo wiersz, uwaga.odpowiedz dopisuje komentarz.

Błędy i ponowienia

Odpowiedź 2xx oznacza dostarczenie. Inny kod albo brak odpowiedzi — wysyłka wraca do kolejki i ponawia się sama: po 1, 5, 15, 30 i 60 minutach, potem po 3 i 6 godzinach. Po ósmej nieudanej próbie (ok. 11 godzin) dostaje status „porzucona”, a w dzienniku wysyłek w projekcie pojawia się przycisk „Ponów”. Webhook działa w jedną stronę: statusów z Twojego systemu nie pobieramy.

Ze względów bezpieczeństwa Zauwaguj nie wysyła webhooków na adresy w sieci lokalnej (localhost, 10.x, 192.168.x).

Najczęstsze pytania

Gotowe integracje bez konfiguracji: ClickUp, Asana, Jira, monday.com, Notion i osTicket. Wolisz asystenta AI? Zobacz serwer MCP.