Webhooks

Webhooks trimit fiecare schimbare pe care o observă agenții la o adresă a ta, pe loc, ca uneltele tale să poată face ceva cu ea: un mesaj în chatul echipei când un produs se epuizează, un rând într-un tabel când scad vânzările, un tichet când trimiterea emailurilor este oprită. Se află la Setări → Webhooks.

Cum adaug o adresă?Copy Anchor Link

Un spațiu de lucru poate avea cel mult cinci adrese. O adresă cu Toate tipurile de evenimente primește și tipurile adăugate mai târziu; una cu o listă primește doar ce e pe ea.

Cum schimb sau pun pe pauză o adresă?Copy Anchor Link

• Editează (creionul) schimbă adresa sau tipurile ei de evenimente. Secretul rămâne același.
• Comutatorul de lângă adresă o pune pe pauză. Cât timp e pe pauză nu i se trimite nimic nou; ce aștepta pleacă atunci când o pornești din nou. Un test se trimite totuși, pentru că l-ai cerut tu.
• Elimină (coșul) oprește definitiv trimiterea. Ce a fost deja trimis rămâne în lista de evenimente.

Ce se trimite?Copy Anchor Link

Fiecare eveniment este un POST cu un corp JSON:

{
  "id": "<event id>",
  "type": "signal",
  "createdAt": "2026-10-14T09:12:00.000Z",
  "workspace": "magazinul-meu",
  "data": {
    "kind": "stock.out",
    "agent": "maestro",
    "subject": { "type": "shop_product", "id": "<product id>" },
    "facts": { "productId": "<product id>", "title": "Cană ceramică", "units": 14 },
    "text": { "en": "\"Cană ceramică\" sold out", "ro": "„Cană ceramică” s-a epuizat" },
    "link": "https://kooga.io/o/magazinul-meu/store/products"
  }
}

• id este id-ul evenimentului. Același eveniment trimis de două ori (o reîncercare după ce adresa ta a răspuns prea târziu) are același id, așa că îl poți sări.
• type este signal, sau test pentru evenimentul trimis de butonul Trimite un test.
• data.kind spune ce s-a schimbat (vezi tabelul de mai jos), iar data.facts conține cifrele din spatele schimbării. Ce cifre sunt acolo depinde de tip.
• data.text este rândul pe care l-ai citi în Kooga, în engleză și română.
• data.link deschide locul din Kooga unde să te uiți.

Pot apărea tipuri noi. Le ignori pe cele pe care nu le folosești.

Cum verific că un eveniment vine de la Kooga?Copy Anchor Link

Fiecare eveniment are aceste antete:

Semnătura este HMAC-SHA256, în hex, al momentului, un punct și corpul brut exact cum a fost primit, calculat cu secretul tău. Ca să o verifici:

În Node.js:

import crypto from 'node:crypto';

function fromKooga(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(part => part.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && expected.length === parts.v1?.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Dacă un secret ajunge unde nu trebuie, alege Secret nou lângă adresă. Cel vechi nu mai funcționează din acel moment.

Ce se întâmplă când adresa mea nu răspunde?Copy Anchor Link

Răspunde cu orice cod 2xx în cel mult zece secunde și evenimentul e considerat livrat. Orice altceva, inclusiv o redirecționare, se reîncearcă: după un minut, cinci minute, treizeci de minute, două ore și douăsprezece ore. După a șasea încercare evenimentul e abandonat. O adresă căzută o după-amiază tot primește totul.

Cât timp trimiterile la o adresă eșuează, ea apare ca Eșuează. Următorul eveniment care trece șterge starea.

Unde văd ce s-a trimis?Copy Anchor Link

Lista Evenimente de sub adrese cuprinde fiecare eveniment din ultimele 30 de zile, cele mai noi primele. O poți filtra după stare, tip de eveniment sau adresă, iar Reîncarcă o citește din nou. Alege un eveniment ca să vezi:

• id-ul lui și adresa la care a plecat,
• corpul exact cum a fost trimis,
• fiecare încercare: codul cu care a răspuns adresa ta (sau Niciun răspuns), când și cât a durat, cele mai noi primele; iar cât timp așteaptă, când e următoarea încercare.

Trimite din nou trimite încă o dată un eveniment, cu o nouă serie de șase încercări: unul abandonat sau unul pe care receptorul tău l-a pierdut. Își păstrează id-ul, așa că un receptor care sare peste id-urile văzute sare și peste el. Evenimentele se păstrează 30 de zile.

Ce urmeazăCopy Anchor Link

Aceleași schimbări ajung la tine în Kooga ca carduri pe Acasă, iar ce fac agenții cu fiecare tip alegi în Reguli.