Logo PDFHQ

Dokumenty

DokumentacjaAutomatyzacja i integracje

Webhooki klientów i dostarczanie zdarzeń

Podpisana dostawa HTTPS o określonym zakresie z transakcyjnej skrzynki nadawczej zdarzenia PDFHQ: subskrybuj, obracaj, odtwarzaj ponownie, anuluj subskrypcję. Domyślnie wyłączone do czasu akceptacji wersji tymczasowej.

Klucze API po stronie serwera Podpisane przesyłanie danych do magazynu

Trwały model zdarzeń i bramkowanie#

PDFHQ przechwytuje wybrane zmiany stanu PDF, AI i podpisywania w tej samej transakcji bazy danych, co zmiana stanu. Oddzielny proces roboczy rozdziela zdarzenia o określonym zakresie i podpisuje posty HTTPS zawierające wyłącznie metadane. Funkcje są wyłączone, chyba że PDFHQ_CUSTOMER_WEBHOOKS_ENABLED=true a operator zapewnia trwały klucz szyfrujący i zaplanowanego pracownika. To jest implementacja źródłowa, a nie umowa SLA dotycząca dostawy produkcyjnej.

Własność projektu jest ustalana z x-api-key należący do HQTools. Zadania dostępne wyłącznie w przeglądarce nie są automatycznie przesyłane do innych projektów. Typy wydarzeń: pdf.job.succeeded, pdf.job.failed, ai.job.succeeded, ai.job.failed, signature.sent, signature.viewed, signature.declined, signature.archived, signature.voided, integration.test. Zarchiwizowane oznacza, że ​​podpisane dane wyjściowe zostały zweryfikowane i zapisane; wysłane/obejrzane nie oznaczają zakończenia podpisywania.

Subskrybuj, zweryfikuj i anuluj
# API key must be held in a server-side secret store.
curl -X POST 'https://api.pdfhq.io/v1/webhooks' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"target_url":"https://customer.example.com/pdfhq/events","events":["pdf.job.succeeded","ai.job.succeeded"]}'
# Save the returned secret once: verify HMAC SHA-256 over timestamp + "." + exact JSON bytes.
# Headers: X-PDFHQ-Webhook-Id, X-PDFHQ-Webhook-Timestamp, X-PDFHQ-Webhook-Signature: v1=hex
# Reject payloads older than 300 seconds. Dedupe on event id.
curl -X DELETE 'https://api.pdfhq.io/v1/webhooks/SUBSCRIPTION_UUID' -H 'x-api-key: YOUR_API_KEY'

Ponawianie prób dostawy, rotacja i prywatność#

Zdarzenia są dostarczane co najmniej raz; odbiorcy muszą deduplikować według identyfikatora zdarzenia. Ponów próbę błędów sieci, HTTP 408, 429 i 5xx z ograniczoną wycofywaniem; HTTP 3xx i większość innych 4xx są ostateczne i przekierowania nigdy nie są wykonywane. Po ośmiu próbach dostarczanie staje się martwe i można je jawnie odtworzyć. Wyświetl GET /v1/webhooks/deliveries?subscription_id=UUID ; odtworzyć przez POST /v1/webhooks/deliveries/UUID/replay. Sekrety można obracać za pomocą POST /v1/webhooks/UUID/rotate, odsłaniając raz nowy klucz. Konsumenci muszą natychmiast zainstalować nowy klucz; ponownie podłącz Zap podczas obracania sekretu podpisu.

Dostarczany jest tylko typ źródła, operacja, identyfikator zdarzenia i identyfikator źródła. Bajty PDF, odpowiedzi AI, adres e-mail osoby podpisującej, podpisane adresy URL i tajemnice rozliczeniowe nie są uwzględniane. Wszystkie miejsca docelowe dostawy muszą być rozpoznawane na publicznych adresach HTTPS i ponownie weryfikowane w momencie wysyłania poprzez weryfikację przypiętych adresów IP i nazwy hosta TLS. Unikaj osadzania wrażliwych parametrów zapytania w adresach URL wywołań zwrotnych.

Prywatny łącznik Zapiera →
Logo PDFHQ

Narzędzia PDF i inteligencja dokumentów. Przygotuj, zrozum i pracuj ze swoimi dokumentami.

© 2026 PDFHQ. Wszystkie prawa zastrzeżone.