Webhooki

Webhooki wychodzące powiadamiają Twój system o zdarzeniach na platformie w czasie rzeczywistym — zamiast odpytywać API, dostajesz POST na wskazany adres URL.

Webhooki są dostępne w pakietach Commerce i wyższych. Konfiguruje je administrator konta; każdy webhook ma adres docelowy, opcjonalny sekret podpisu i listę subskrybowanych zdarzeń (dostępne jest też dostarczenie testowe do weryfikacji odbiornika).

Zdarzenia

Zdarzenie	Kiedy
visibility.check_completed	po zakończeniu zbiorczego sprawdzenia widoczności (np. nocny monitoring)
content.published	po publikacji treści do CMS (WordPress / Webflow)
alert.triggered	gdy zadziała alert (np. spadek SoV, nowy konkurent)
attribution.order_synced	po przyjęciu zamówienia przez API (POST /v1/orders)

Format dostarczenia

POST z ciałem JSON:

{
  "event": "alert.triggered",
  "timestamp": "2026-07-22T06:15:00+00:00",
  "workspace_id": "…",
  "tenant_id": "…",
  "data": { /* szczegóły zależne od zdarzenia */ }
}

Nagłówki:

• X-GEO-Event — nazwa zdarzenia,
• X-GEO-Signature — podpis sha256=<hex> (jeśli ustawiono sekret),
• User-Agent: GEO-Platform-Webhooks/1.0.

Weryfikacja podpisu

Podpis to HMAC-SHA256 z surowego ciała żądania, kluczem jest sekret webhooka:

import hashlib, hmac

def verify(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Licz HMAC na bajtach ciała dokładnie tak, jak przyszły — przed jakimkolwiek parsowaniem JSON (reserializacja zmienia bajty i unieważnia podpis).

Wymagania wobec odbiornika

• Odpowiedz kodem 2xx — wszystko inne traktujemy jako niepowodzenie dostarczenia.
• Odpowiadaj szybko (limit 10 s) — przyjmij zdarzenie, odłóż przetwarzanie do kolejki.
• Bądź idempotentny — zaprojektuj odbiornik tak, by powtórzone zdarzenie nie zdublowało skutków.

Najczęstsze pytania

Jak odróżnić środowisko testowe od produkcji? Użyj osobnych adresów odbiornika; dostarczenie testowe pozwala zweryfikować odbiornik przed włączeniem realnych zdarzeń.

Co jeśli mój serwer był chwilowo niedostępny? Status ostatniego dostarczenia jest zapisywany. Zdarzenia mają charakter powiadomień — stan źródłowy zawsze możesz dociągnąć przez API.