Webhooki

Odbieraj zdarzenia z rozmów, sesji botów i zadań w czasie rzeczywistym — podpisane HMAC, dostarczane co najmniej raz.

Webhook to POST z kopertą JSON, który Mediflo wysyła pod Twój adres, gdy w systemie coś się wydarzy: bot skończył rozmowę, transkrypcja jest gotowa, powstało zadanie. Zamiast odpytywać API, dostajesz zdarzenie od razu.

Katalog zdarzeń

Każdy typ zdarzenia z polskim opisem, blokami danych i przykładową kopertą.

Weryfikacja podpisu

Nagłówki, wzór HMAC i gotowy kod w TypeScript i PHP.

Gwarancje dostarczania

Co najmniej raz, brak kolejności, drabinka ponowień, automatyczne wyłączenie.

Testowanie

Zdarzenie testowe, podgląd dostarczeń i ponowna wysyłka.

Jak zarejestrować endpoint

Masz dwie drogi, obie dają ten sam rezultat.

W aplikacji: Ustawienia → Integracje → zakładka Webhooki → „Dodaj webhook". Podajesz adres https://, wybierasz typy zdarzeń (albo * dla wszystkich) i opcjonalne bloki danych. Sekret podpisu pokazujemy tylko raz, zaraz po utworzeniu.

Przez API: klucz z zakresem webhooks.write i jedno żądanie:

curl -X POST https://app.mediflo.ai/api/external/v1/webhook-endpoints \
  -H "Authorization: Bearer mflo_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://twoj-system.example.com/mediflo/webhooks",
    "eventTypes": ["bot_call.completed", "task.created"],
    "payloadBlocks": ["outcome"]
  }'

Odpowiedź zawiera id endpointu i pole secret — zapisz je od razu, żaden endpoint nie zwróci go ponownie. Pełny opis pól znajdziesz w referencji: POST /webhook-endpoints.

Adres docelowy

Rejestruj końcowy adres https://. Przekierowania 3xx liczymy jako nieudane dostarczenie i nigdy za nimi nie podążamy.

Co przychodzi pod Twój adres

Każde dostarczenie to POST z ciałem JSON i czterema nagłówkami Mediflo. Koperta ma zawsze pola id, type, apiVersion, occurredAt i data:

{
  "id": "evt_01J8Z…",
  "type": "task.created",
  "apiVersion": "v1",
  "occurredAt": "2026-09-07T08:15:00.000Z",
  "data": { "…": "…" }
}

apiVersion to dziś v1. Nowe pola wewnątrz data dodajemy bez zmiany wersji, więc parsuj pobłażliwie: ignoruj nieznane klucze i nie odrzucaj nieznanego typu zdarzenia, zwłaszcza przy subskrypcji *.

Bloki z danymi osobowymi

Zdarzenia z rodzin bot_call i call mogą nieść dodatkowe bloki: numery telefonów, wynik rozmowy, transkrypcję, kontakt. Domyślnie są wyłączone — włączasz je świadomie per webhook, bo to dane osobowe, w tym dane wrażliwe. Które zdarzenia je obsługują, widać w katalogu zdarzeń.