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"]
}' | jq
| 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 |
URL musi używać protokołu HTTPS. Adresy HTTP nie są akceptowane.
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..."
}
}
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 |
folder.created | Utworzono nowy folder |
folder.updated | Zaktualizowano folder |
folder.deleted | Usunięto folder |
media.uploaded | Przesłano nowy plik multimedialny |
generation.started | Rozpoczęto generowanie wideo AI |
generation.completed | Zakończono generowanie wideo AI |
generation.failed | Generowanie wideo AI nie powiodło się |
share.created | Utworzono link udostępniania |
share.updated | Zaktualizowano ustawienia udostępniania |
share.deleted | Usunięto link udostępniania |
POST z body JSON:
{
"id": "evt_a1b2c3d4-...",
"type": "document.created",
"timestamp": "2026-03-28T12:00:00Z",
"user_id": "u1234567-...",
"workspace_id": null,
"resource_type": "document",
"resource_id": "d1234567-...",
"payload": {
"title": "Nowy tutorial"
}
}
Weryfikacja podpisu
Każde powiadomienie zawiera nagłówek X-Clarife-Signature w formacie:
X-Clarife-Signature: t=1711612800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9
timestamp.body kluczem secret:
import crypto from "node:crypto";
function verifyWebhookSignature(body, signature, 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}.${body}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(computed),
Buffer.from(expectedSig)
);
}
Zawsze używaj timingSafeEqual do porównywania podpisów, aby zapobiec atakom timing-based.
Polityka ponowień
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 10 sekundach |
| 4 | po 60 sekundach |
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" | jq
webhook.test na skonfigurowany URL.
Limity
| Plan | Maksymalna liczba subskrypcji |
|---|
| Pro | 3 |
| Business | 20 |
