Webhooki
Webhooki umożliwiają otrzymywanie powiadomień HTTP w czasie rzeczywistym, gdy w clarife zachodzą zdarzenia (np. utworzenie dokumentu, upload mediów, zmiana udostępnienia).
Tworzenie subskrypcji
curl -s -X POST https://my.clarife.app/api/webhooks/subscriptions \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Mój webhook",
"url": "https://example.com/webhooks/clarife",
"events": ["document.created", "document.updated", "share.created"]
}' | jqParametry body:
| Pole | Typ | Wymagane | Opis |
|---|---|---|---|
| name | string | tak | Nazwa subskrypcji (1-100 znaków) |
| url | string | tak | URL endpointu HTTPS (max 2048 znaków) |
| events | string[] | tak | Lista typów zdarzeń do subskrypcji |
⚠️ Uwaga: URL musi używać protokołu HTTPS. Adresy HTTP nie są akceptowane.
Odpowiedź 201 Created:
{
"subscription": {
"id": "ws1234-...",
"name": "Mój webhook",
"url": "https://example.com/webhooks/clarife",
"events": ["document.created", "document.updated", "share.created"],
"active": true,
"failure_count": 0,
"created_at": "2026-03-28T12:00:00Z",
"secret": "whsec_a1b2c3d4e5f6..."
}
}⚠️ Uwaga: Pole secret jest wyświetlane tylko raz przy tworzeniu subskrypcji. Skopiuj je i przechowuj bezpiecznie - będzie potrzebne do weryfikacji podpisów.
Typy zdarzeń
| Zdarzenie | Opis |
|---|---|
| document.created | Utworzono nowy dokument |
| document.updated | Zaktualizowano dokument |
| document.deleted | Usunięto dokument (soft delete) |
| project.created | Utworzono nowy projekt |
| project.updated | Zaktualizowano projekt |
| project.deleted | Usunięto projekt |
| project.moved | Przeniesiono projekt do innego folderu |
| folder.created | Utworzono nowy folder |
| folder.updated | Zaktualizowano folder |
| folder.deleted | Usunięto folder |
| media.uploaded | Przesłano nowy plik multimedialny |
| generation.completed | Zakończono generowanie wideo AI |
| share.created | Utworzono link udostępniania |
| share.viewed | Wyświetlono link udostępniania |
| share.updated | Zaktualizowano ustawienia udostępniania |
| share.deleted | Usunięto link udostępniania |
| workspace.member_added | Dodano członka do workspace |
| workspace.member_removed | Usunięto członka z workspace |
Format payload
Każde powiadomienie webhook jest wysyłane jako POST z body JSON oraz nagłówkami X-Clarife-Event (typ zdarzenia) i X-Clarife-Delivery (ID dostawy):
{
"id": "evt_a1b2c3d4-...",
"event": "document.created",
"created_at": "2026-03-28T12:00:00Z",
"data": {
"title": "Nowy tutorial"
}
}Weryfikacja podpisu
Każde powiadomienie zawiera nagłówek X-Clarife-Signature w formacie:
X-Clarife-Signature: t=1711612800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9Aby zweryfikować autentyczność, oblicz HMAC-SHA256 z ciągu timestamp.deliveryId.body kluczem secret, gdzie deliveryId to wartość nagłówka X-Clarife-Delivery (równa polu id w body):
import crypto from "node:crypto";
function verifyWebhookSignature(rawBody, signature, deliveryId, secret) {
const [tPart, v1Part] = signature.split(",");
const timestamp = tPart.replace("t=", "");
const expectedSig = v1Part.replace("v1=", "");
// Ochrona przed atakami replay (5 minut)
const age = Math.abs(Date.now() / 1000 - parseInt(timestamp));
if (age > 300) {
throw new Error("Webhook timestamp too old");
}
const computed = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${deliveryId}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(computed),
Buffer.from(expectedSig)
);
}💡 Wskazówka: Licz HMAC na surowym body (bez ponownej serializacji JSON) i zawsze używaj timingSafeEqual do porównywania podpisów, aby zapobiec atakom timing-based.
Polityka ponowień
Limit czasu odpowiedzi to 10 sekund. Jeśli Twój endpoint nie zwróci odpowiedzi 2xx, clarife podejmie ponowne próby:
| Próba | Opóźnienie |
|---|---|
| 1 | natychmiast |
| 2 | po 1 sekundzie |
| 3 | po 5 sekundach |
| 4 | po 15 sekundach |
Zdarzenia, których nie udało się dostarczyć, są dodatkowo ponawiane okresowo przez system w tle.
Auto-dezaktywacja
Po 10 kolejnych niepowodzeniach subskrypcja jest automatycznie dezaktywowana (active: false). Możesz ją ponownie aktywować ręcznie w ustawieniach po naprawieniu endpointu.
Endpoint testowy
Możesz wysłać testowe zdarzenie do swojego endpointu:
curl -s -X POST https://my.clarife.app/api/webhooks/subscriptions/SUBSCRIPTION_ID/test \
-H "Authorization: Bearer TOKEN" | jqWysyła zdarzenie testowe typu test.ping na skonfigurowany URL.
Limity
| Plan | Maksymalna liczba subskrypcji |
|---|---|
| Pro | 3 |
| Business | 20 |