Dokumentacja API
Zdarzenia
Webhooki
Onboardly wysyła zdarzenia do skonfigurowanego adresu URL, gdy zmienia się stan onboardingu lub weryfikacji KYC. Każdy ładunek jest podpisany HMAC-SHA256, dzięki czemu możesz zweryfikować jego autentyczność.
Typy zdarzeń
onboarding.created | utworzono nowy proces onboardingu. |
onboarding.completed | pracownik ukończył onboarding. |
onboarding.signed | dokument został podpisany. |
onboarding.fully_signed | wszystkie strony podpisały dokumenty. |
kyc.passed | weryfikacja tożsamości zakończona sukcesem. |
kyc.failed | weryfikacja tożsamości nie powiodła się. |
Format ładunku
Ładunek jest wysyłany metodą POST jako JSON:
{
"event": "onboarding.completed",
"tenantId": "uuid",
"companyId": "uuid",
"onboardingId": "uuid",
"timestamp": "2026-07-14T12:00:00.000Z",
"data": { /* zależne od typu zdarzenia */ }
}Nagłówki
X-Onboardly-Signature | podpis HMAC-SHA256 treści żądania, kluczem webhookSecret tenanta. |
X-Onboardly-Event | typ zdarzenia (np. onboarding.completed). |
Weryfikacja podpisu
Policz HMAC-SHA256 z surowej treści żądania używając sekretu webhooka (dostępny w ustawieniach tenanta) i porównaj wynik z nagłówkiem X-Onboardly-Signature w sposób odporny na atak czasowy. Odrzuć żądanie, jeśli podpisy się nie zgadzają.
import crypto from "node:crypto";
function verifyOnboardlyWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody, "utf8")
.digest("hex");
// porównanie w stałym czasie
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}Weryfikuj na surowym ciele
Policz HMAC zanim ciało zostanie sparsowane do obiektu — ponowna serializacja JSON może zmienić bajty i unieważnić podpis.Ponawianie i kolejność
Dostarczanie odbywa się z trwałej kolejki z ponawianiem według harmonogramu 1 min → 5 min → 30 min → 2 h → 12 h (6 prób; po wyczerpaniu zdarzenie trafia do stanu dead). Odpowiedz kodem 2xx możliwie szybko; cięższą pracę wykonuj asynchronicznie. Zaprojektuj odbiornik idempotentnie — to samo zdarzenie może dotrzeć więcej niż raz.