Webhooki
Otrzymuj powiadomienia o zdarzeniach w czasie rzeczywistym.
Webhooki pozwalają reagować na zdarzenia takie jak zakończenie indeksowania źródła czy błąd przetwarzania. Tutaj znajdziesz listę zdarzeń, format ładunku i sposób weryfikacji podpisu.
Zdarzenia
Webhook jest wywoływany metodą POST na skonfigurowany adres URL za każdym razem, gdy w projekcie zajdzie jedno z poniższych zdarzeń.
| Zdarzenie | Opis |
|---|---|
| source.indexed | Źródło zostało przetworzone i jest gotowe w rozmowach. |
| source.failed | Przetwarzanie źródła nie powiodło się — sprawdź szczegóły błędu. |
| project.updated | Zmieniła się konfiguracja projektu (nazwa, model lub ustawienia). |
Format ładunku
Każde wywołanie zawiera ładunek JSON z trzema polami: event (nazwa zdarzenia), data (szczegóły zależne od typu) oraz created_at (znacznik czasu w formacie ISO 8601).
{
"event": "source.indexed",
"data": {
"source_id": "src_91",
"project_id": "proj_abc",
"title": "Regulamin HR.pdf",
"status": "ready"
},
"created_at": "2026-06-25T10:32:00Z"
}Weryfikacja podpisu
Każde żądanie zawiera nagłówek X-Raggy-Signature — podpis HMAC-SHA256 wyliczony z surowego ciała żądania i Twojego sekretu webhooka. Po stronie odbiorcy policz podpis z tego samego sekretu i porównaj wartości, aby potwierdzić, że żądanie pochodzi od raggy.
Zawsze weryfikuj podpis: Porównuj podpisy metodą odporną na ataki czasowe i odrzucaj żądania bez prawidłowego nagłówka X-Raggy-Signature.
Ponawianie
Endpoint powinien odpowiedzieć kodem 2xx w ciągu kilku sekund. Jeśli zwróci błąd lub przekroczy limit czasu, raggy ponowi dostarczenie kilka razy z rosnącym odstępem.
Idempotencja: Z powodu ponawiania to samo zdarzenie może dotrzeć więcej niż raz. Używaj pola source_id lub created_at, aby pomijać duplikaty.
Ładunki i pola danych odpowiadają zasobom opisanym w API Reference.