Odbieranie zgłoszeń z Twojego formularza

Masz już formularz i nie chcesz go wymieniać? Wyślij z niego zgłoszenie do OctaForms webhookiem. Lead trafi do tej samej skrzynki co pozostałe, z tymi samymi powiadomieniami, webhookami wychodzącymi i eksportem.

Co dostajesz w panelu

Załóż formularz i wybierz tryb Webhook. Zamiast budowania pól zobaczysz zakładkę Odbieranie, a w niej trzy rzeczy do przeniesienia na swoją stronę:

• Adres, pod który wysyłasz zgłoszenia,
• sekret podpisu, którym je podpisujesz,
• tabelę typów pól, w której mówisz, które pole jest e-mailem, a które telefonem.

Wyślij zgłoszenie

POST https://app.octaforms.pl/api/v1/public/inbound/TWOJ_KLUCZ
Content-Type: application/json
X-Octa-Forms-Signature: sha256=PODPIS

{
  "id": "1042",
  "form_name": "Formularz kontaktowy",
  "created": "2026-07-31T09:20:00+02:00",
  "fields": {
    "imie": "Anna",
    "email": "anna@firma.pl",
    "telefon": "+48 500 100 200",
    "zgoda": true
  },
  "meta": {
    "referrer": "https://google.com"
  }
}

Wymagane jest tylko fields. Pole id to Twój identyfikator zgłoszenia i decyduje o odporności na powtórki, więc warto go wysyłać.

Podpis

Podpis to HMAC SHA-256 z dokładnie tych bajtów, które wysyłasz, kluczem z panelu.

$body = json_encode($payload);
$signature = 'sha256=' . hash_hmac('sha256', $body, $secret);

Podpisuj gotowe ciało i wyślij je bez żadnych zmian. Jeśli po podpisaniu przebudujesz JSON (inna kolejność kluczy, inne wcięcia), podpis przestanie się zgadzać.

Nie potrafisz podpisać? Wyłącz w panelu Wymagaj podpisu. Wtedy Twój adres jest jedynym zabezpieczeniem, więc traktuj go jak hasło, a limit zgłoszeń na godzinę będzie niższy.

Kontrakt „Ogólny (JSON)“

Jeśli Twoja usługa nie pozwala ułożyć ciała po swojemu, ustaw dostawcę na Ogólny (JSON). Obietnica jest prosta:

Wyślij JSON. Weźmiemy fields, jeśli jest. Jeśli nie ma, weźmiemy całe ciało.

Czyli to też zadziała:

{ "imie": "Anna", "email": "anna@firma.pl" }

Gdy nie wyślesz id, policzymy je z treści zgłoszenia. Skutek: wysłanie dwa razy identycznej treści da jednego leada.

Odpowiedzi

Każda odpowiedź ma ten sam kształt: {"status": "…", "leadId": "…", "detail": "…"}.

Kod	status	Co znaczy
201	accepted	lead zapisany
200	duplicate	to zgłoszenie już mamy, nie zapisaliśmy drugi raz
200	test	zgłoszenie testowe, zwracamy listę rozpoznanych pól
200	ignored	formularz jest wyłączony w panelu
401	bad_signature	brak albo błędny podpis
404	unknown_key	nieznany adres
413	too_large	ciało większe niż 256 KB
415	unsupported_media	brak Content-Type: application/json
422	unreadable	nie widzimy zgłoszenia w tym ciele
429	rate_limited	przekroczony godzinny limit

Kody 200 przy duplicate i ignored są celowe: to stany zamierzone, a nie błędy po Twojej stronie, więc nie ma czego ponawiać.

Odporność na powtórki

Zgłoszenie z tym samym id na tym samym formularzu tworzy jednego leada, choćbyś wysłał je dziesięć razy. Nie powstaje też drugi komplet powiadomień. Możesz więc bezpiecznie ponawiać przy błędzie sieci albo timeoucie.

Przycisk testowy

Dodaj "test": true, a odpowiemy listą rozpoznanych pól i nie utworzymy leada:

{ "test": true, "fields": { "imie": "Jan", "email": "jan@example.com" } }

{ "status": "test", "recognizedFields": ["imie", "email"] }

To najszybszy sposób sprawdzenia adresu, podpisu i nazw pól bez wstawiania testowej osoby do skrzynki klienta.

Ustaw typy pól

Po pierwszym zgłoszeniu w tabeli typów pojawią się nazwy pól, które przysłałeś. Ustaw je.

Od typów zależy maskowanie danych kontaktowych w webhookach i powiadomieniach, podgląd kontaktu na liście leadów i lista tokenów w szablonach wiadomości. Pole bez typu jest traktowane jak zwykły tekst, więc nie zostanie zamaskowane, nawet jeśli anonimizacja jest włączona.

Rzeczy, które warto wiedzieć

• Czas zgłoszenia liczymy własnym zegarem. Twój created zapisujemy obok, w danych leada, ale kolejność w skrzynce ustala moment, w którym zgłoszenie do nas dotarło. Dzięki temu zaległości wysłane po awarii lądują na górze listy, a nie w jej środku.
• Nazw pól nie zmieniamy. Twoje imię zostaje Twoje imię. Uwaga: jako {token} w szablonie e-maila zadziała tylko nazwa z małych liter, cyfr i podkreśleń.
• Plików nie przyjmujemy. Wyślij opis pliku ({"name": "cv.pdf", "mime": "application/pdf", "size": 84213}), a pokażemy go jako cv.pdf (PDF, 82 KB).
• Zgłoszeń nie walidujemy. Skoro powstało u Ciebie, odrzucenie go byłoby po prostu utratą danych.

Rotacja kluczy

• Klucz w adresie wymieniasz, gdy adres wyciekł. Stary przestaje działać natychmiast, więc wklej nowy po swojej stronie od razu.
• Sekret podpisu ma okres przejściowy: po wymianie stary nadal weryfikuje zgłoszenia, dopóki go nie wycofasz. Przepnij się spokojnie i dopiero wtedy kliknij „Wycofaj poprzedni sekret“.