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

bash
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

Parametry body:

PoleTypWymaganeOpis
namestringtakNazwa subskrypcji (1-100 znaków)
urlstringtakURL endpointu HTTPS (max 2048 znaków)
eventsstring[]takLista typów zdarzeń do subskrypcji

⚠️ Uwaga: URL musi używać protokołu HTTPS. Adresy HTTP nie są akceptowane.

Odpowiedź 201 Created:

json
{
  "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ń

ZdarzenieOpis
document.createdUtworzono nowy dokument
document.updatedZaktualizowano dokument
document.deletedUsunięto dokument (soft delete)
project.createdUtworzono nowy projekt
project.updatedZaktualizowano projekt
project.deletedUsunięto projekt
project.movedPrzeniesiono projekt do innego folderu
folder.createdUtworzono nowy folder
folder.updatedZaktualizowano folder
folder.deletedUsunięto folder
media.uploadedPrzesłano nowy plik multimedialny
generation.completedZakończono generowanie wideo AI
share.createdUtworzono link udostępniania
share.viewedWyświetlono link udostępniania
share.updatedZaktualizowano ustawienia udostępniania
share.deletedUsunięto link udostępniania
workspace.member_addedDodano członka do workspace
workspace.member_removedUsunię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):

json
{
  "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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8f9

Aby 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):

javascript
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óbaOpóźnienie
1natychmiast
2po 1 sekundzie
3po 5 sekundach
4po 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:

bash
curl -s -X POST https://my.clarife.app/api/webhooks/subscriptions/SUBSCRIPTION_ID/test \
  -H "Authorization: Bearer TOKEN" | jq

Wysyła zdarzenie testowe typu test.ping na skonfigurowany URL.

Limity

PlanMaksymalna liczba subskrypcji
Pro3
Business20