Webhooki i API REST

Conviro udostępnia webhooki do powiadomień o zdarzeniach w czasie rzeczywistym oraz API REST do programowego dostępu do wszystkich funkcji platformy.

Webhooki

Czym są webhooki?

Webhooki wysyłają żądanie HTTP POST na Twój serwer za każdym razem, gdy w Conviro wystąpi określone zdarzenie. Dzięki temu możesz reagować w czasie rzeczywistym, bez odpytywania (polling).

Dostępne zdarzenia

Zdarzenie	Kiedy się uruchamia
`message.new`	Zostaje wysłana nowa wiadomość (przez odwiedzającego lub bota)
`session.started`	Rozpoczyna się nowa sesja rozmowy
`session.closed`	Rozmowa zostaje zamknięta
`session.escalated`	Rozmowa zostaje eskalowana
`lead.captured`	Zostaje pozyskany nowy lead
`lead.created`	Zostaje utworzony rekord leada
`lead_form.submitted`	Zostaje wysłany formularz leada
`handoff.requested`	Zostaje zgłoszone przekazanie do konsultanta
`csat.submitted`	Zostaje przesłana ocena CSAT
`csat.received`	Zostaje zapisany wynik CSAT
`ai.failed`	AI nie potrafi wygenerować odpowiedzi
`ticket.created`	Zostaje otwarte zgłoszenie do wsparcia
`ticket.resolved`	Zgłoszenie do wsparcia zostaje rozwiązane
`contact.created`	Zostaje utworzony nowy kontakt
`contact.updated`	Kontakt zostaje zaktualizowany
`contact.merged`	Dwa kontakty zostają scalone
`contact.deleted`	Kontakt zostaje usunięty

Formularz webhooka udostępnia też opcję Wszystkie zdarzenia, która subskrybuje każde ze zdarzeń powyżej (zapisywana jako symbol wieloznaczny *); pojedynczy webhook przyjmuje również listę nazw zdarzeń rozdzieloną przecinkami.

Konfiguracja

Przejdź do Dashboard -> Deweloperzy -> Webhooki.
Kliknij Add Webhook.
Podaj adres URL swojego endpointu (musi być HTTPS).
Wybierz zdarzenia, które chcesz otrzymywać.
Kliknij Save.

Bezpieczeństwo: podpisywanie HMAC-SHA256

Każdy ładunek webhooka jest podpisywany algorytmem HMAC-SHA256 przy użyciu Twojego sekretu webhooka. Zweryfikuj podpis na swoim serwerze, aby potwierdzić autentyczność:

X-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt>          # only on a retried delivery

Skrót jest liczony z <unix_timestamp>.<surowe_ciało_żądania>, więc weryfikacja samego ciała nigdy się nie zgodzi. Podziel nagłówek po ,, odczytaj wartości t= i v1=, przelicz ponownie HMAC-SHA256 z t + '.' + rawBody używając swojego webhook secret i porównaj oba skróty w stałym czasie. Odrzucaj dostawy, których znacznik czasu jest starszy niż kilka minut, aby przechwycony ładunek nie mógł zostać odtworzony. Uwaga: Wyślij test na adres URL, który nie jest zapisanym webhookiem, jest dostarczany bez podpisu — nie ma sekretu do podpisania; przetestuj weryfikację na zapisanym endpoincie.

Zasady ponawiania

Jeśli Twój endpoint zwróci kod statusu inny niż 2xx, Conviro ponawia próbę maksymalnie 3 razy z wykładniczym opóźnieniem (1 min, 5 min, 30 min).

API REST

Uwierzytelnianie

Wygeneruj klucz API w Dashboard -> Deweloperzy -> Klucze API -> Utwórz klucz API.
Dołącz go do nagłówka Authorization:

Authorization: Bearer sk_your_api_key_here

> Klucz jest pokazywany tylko raz. Utworzenie klucza wymaga co najmniej jednego zakresu (scope) — Utwórz pozostaje nieaktywny, dopóki go nie wybierzesz — a pełna wartość sk_ pojawia się jeden jedyny raz, w oknie, które celowo nie zamyka się klawiszem Escape ani kliknięciem w tło. Później czytelny pozostaje wyłącznie prefiks; reszta to skrót bcrypt i nie da się jej odzyskać. Skopiuj klucz przed zamknięciem okna. Jeśli go zgubisz, utwórz nowy i unieważnij stary.

Najważniejsze endpointy

Metoda	Endpoint	Opis
GET	`/api/chatbots`	Wyświetla listę wszystkich chatbotów
GET	`/api/chatbots/:id`	Pobiera szczegóły chatbota
GET	`/api/sessions`	Wyświetla listę sesji (z filtrami)
GET	`/api/sessions/:id/messages`	Pobiera wiadomości z sesji
POST	`/api/sessions/:id/messages`	Wysyła wiadomość do sesji
GET	`/api/contacts`	Wyświetla listę kontaktów
POST	`/api/contacts`	Tworzy kontakt
GET	`/api/leads`	Wyświetla listę leadów
POST	`/api/leads`	Tworzy lead
GET	`/api/analytics/overview`	Pobiera podsumowanie analityki

Limity zapytań

Plan Free: 60 zapytań/minutę
Starter: 120 zapytań/minutę
Pro: 300 zapytań/minutę
Growth+: 600 zapytań/minutę

Nagłówki z limitem zapytań są dołączane do każdej odpowiedzi:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Pełna dokumentacja

Odwiedź /developers, aby zobaczyć pełną dokumentację API z przykładami żądań i odpowiedzi.