Skip to Content
WebhooksPrzegląd

Webhooks

Webhooki pozwalają dostawać powiadomienia w czasie rzeczywistym o zdarzeniach w przestrzeni roboczej Ignite. Zamiast odpytywać API o zmiany, webhooki wysyłają dane na Twój serwer, gdy coś się dzieje.

Czym są webhooki?

Webhooki to wywołania HTTP uruchamiane przy określonych zdarzeniach. Gdy coś się wydarzy (np. utworzenie lub aktualizacja wideo), Ignite wysyła żądanie HTTP POST na skonfigurowany endpoint z informacją o zdarzeniu.

Przypadki użycia

  • Synchronizacja z CMS — utrzymuj zewnętrzny system zarządzania treścią zgodny ze zmianami wideo
  • Automatyzacja procesów — uruchamiaj przepływy, gdy wideo jest tworzone, aktualizowane lub usuwane
  • Powiadomienia — informuj zespół o zakończeniu przetwarzania wideo
  • Analityka — śledź cykl życia wideo we własnym systemie analityki

Jak to działa

Utworzenie subskrypcji webhooka

Skonfiguruj subskrypcję w panelu administracyjnym Ignite. Potrzebujesz:

  • adresu URL endpointu na serwerze, który przyjmie żądania HTTP POST
  • typów zdarzeń, na które chcesz subskrybować

Odbieranie zdarzeń

Gdy wystąpi subskrybowane zdarzenie, Ignite wysyła żądanie HTTP POST na Twój endpoint z:

  • typem zdarzenia w nagłówku X-Webhook-Event
  • podpisem do weryfikacji w nagłówku X-Webhook-Signature
  • unikalnym identyfikatorem dostawy w nagłówku X-Webhook-Delivery-Id
  • pełnym obiektem wideo w treści JSON

Przetwarzanie i odpowiedź

Twój endpoint powinien:

  1. Zweryfikować podpis webhooka
  2. Przetworzyć dane zdarzenia
  3. Zwrócić kod statusu 2xx w ciągu 30 sekund

Webhooki mogą przychodzić w innej kolejności lub być dostarczane więcej niż raz. Po Twojej stronie musisz sprawdzać znacznik czasu updatedAt i identyfikator wideo id, żeby zachować właściwą kolejność i spójność danych. Zawsze porównuj przychodzący znacznik z tym, co masz zapisane, zanim zastosujesz aktualizacje, i używaj nagłówka X-Webhook-Delivery-Id, żeby wykrywać duplikaty i je pomijać.

Subskrypcja webhooka

Subskrypcja webhooka to konfiguracja określająca, dokąd wysyłać zdarzenia i które zdarzenia nasłuchiwać.

Właściwości subskrypcji

WłaściwośćTypOpis
idstringUnikalny identyfikator subskrypcji
urlstringAdres URL endpointu, pod który trafią zdarzenia (HTTP lub HTTPS)
eventsobjectKtóre typy zdarzeń są włączone
events.videoCreatedbooleanOtrzymuj zdarzenia przy tworzeniu wideo
events.videoUpdatedbooleanOtrzymuj zdarzenia przy aktualizacji wideo
events.videoDeletedbooleanOtrzymuj zdarzenia przy usuwaniu wideo
activebooleanCzy webhook jest aktywny
signingSecretstringTajny klucz do weryfikacji podpisu (generowany automatycznie)
workspacestringPrzestrzeń robocza, do której należy webhook

Przykładowy obiekt subskrypcji

{
  "id": "507f1f77bcf86cd799439011",
  "url": "https://your-server.com/webhook",
  "events": {
    "videoCreated": true,
    "videoUpdated": true,
    "videoDeleted": false
  },
  "active": true,
  "signingSecret": "whsec_abc123...",
  "workspace": "507f1f77bcf86cd799439000"
}

Format żądania HTTP

Gdy wystąpi zdarzenie, Ignite wysyła żądanie POST na Twój endpoint:

Nagłówki

NagłówekOpis
Content-Typeapplication/json
X-Webhook-EventTyp zdarzenia (np. video.created)
X-Webhook-SignaturePodpis HMAC-SHA256 do weryfikacji
X-Webhook-Delivery-IdUnikalny identyfikator tej dostawy (przydatny przy idempotentności)

Treść

Treść żądania to pełny obiekt wideo w JSON. Pełną strukturę opisuje dokumentacja obiektu wideo.

{
  "id": "507f1f77bcf86cd799439011",
  "title": "My Video",
  "status": "COMPLETE",
  "visibility": "public",
  "duration": 120,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  // ... all other video properties
}

Co dalej

ZapytaniaTypy zdarzeń