Webhooks Overview

Webhooks permite aplicației dvs. să reacționeze atunci când resursele se schimbă în platformă fără a solicitaAPI. Un abonament conectează un endpoint HTTPS la un set de evenimente într-o singură organizație. Când apare un eveniment, platforma trimite o cerere semnată POST care conține o imagine instantanee JSON a resursului afectat.

Utilizările comune includ sincronizarea utilizatorilor și a terților, inițierea fluxurilor de lucru de aprobare a documentelor și înregistrarea evenimentelor de conformitate într-un alt sistem.

What webhooks cover

Webhook subscriptions currently deliver events for:

Domain	Event families
Third parties	third-party:*
Users	user:*
Obligations	obligation:*
Rights requests	right-request:*
Documents	document:*, document-version:*, evenimente de semnare și de aprobare a cvorumului

Alte domenii ale produsului – inclusiv cadre, controale, măsuri, riscuri, recenzii de acces, dispozitive și consimțământul pentru cookie-uri – sunt disponibile prin intermediul GraphQL, the CLI, MCP, and n8nUtilizați sondaje sau o sarcină de reconciliere programată pentru acele domenii atunci când integrarea dvs. trebuie să rămână actuală.

See Event types pentru referința completă a sarcinii pentru evenimentele acceptate.

How it works

sequenceDiagram
  participant P as Probo
  participant E as Your endpoint

  Note over P: A subscribed resource changes
  P->>P: Queue event, poll every ~5s
  P->>+E: POST signed JSON
  E->>E: Verify signature
  E->>E: Reject stale timestamp
  E->>E: Record eventId, enqueue
  E-->>-P: 2xx within 30s
  Note over P,E: Failed deliveries are not retried

O singură livrare, de la schimbarea platformei până la recunoașterea dvs.

1. Expose an HTTPS endpoint

   Punctul dvs. final trebuie să accepte solicitările POST cu un corp application/json.

2. Create a subscription

   In the platform, open Settings > Webhooks, introduceți adresa URL a punctului final și selectați evenimentele care urmează să fie primite.De asemenea, puteți gestiona abonamentele cu CLI.

3. Verify every delivery

   Verificați semnătura împotriva corpului de cerere brută și respingeți timestamp-urile stagnante înainte de a parsa sau de a acționa pe sarcina utilă.

4. Acknowledge quickly

   Răspunsul este 2xx Răspunsul este 2xx .

Endpoint requirements

• The URL must use HTTPS.
• Punctul final trebuie să returneze 200, 201, 202 sau 204.
• The complete response must arrive within 30 seconds.

Orice altă stare, eroare de conexiune sau timing marchează livrarea ca eșuată. platforma nu reanalizează livrările eșuate, astfel încât să monitorizeze istoricul de livrare și să proiecteze un proces de recuperare pentru evenimentele ratate.

Root envelope

Câmpurile specifice resurselor trăiesc sub ___ZBT_I18N_RUNTIME_BLOCK_187__ (și opțional updatedFrom) – ele nu sunt niciodată promovate la rădăcină.

{
  "eventId": "whevt_01ABC123",
  "subscriptionId": "whsub_01DEF456",
  "organizationId": "org_01GHI789",
  "eventType": "document:updated",
  "createdAt": "2026-07-15T10:30:00Z",
  "data": {
    "id": "doc_01VWX234",
    "title": "Information Security Policy"
  },
  "updatedFrom": {
    "id": "doc_01VWX234",
    "title": "InfoSec Policy"
  }
}

Root field	Type	Always present	Description
eventId	string	Yes	ID unic de livrare. Folosește-l ca cheie idempotency
subscriptionId	string	Yes	Abonamentul Webhook care a primit evenimentul
organizationId	string	Yes	Organizația în care a avut loc evenimentul
eventType	string	Yes	Wire-format event name (e.g. document:updated, third-party:created)
createdAt	string	Yes	Când a fost creat evenimentul (RFC 3339)
data	object	Yes	Formă depinde de eventType — vezi Event Types
updatedFrom	object	No	Prezent numai pe evenimentele *:updated. Imaginea completă a aceleiași forme de resursă ca și data, luată înainte de actualizare. Omis pentru crearea, ștergerea, arhivarea, semnătura și alte evenimente care nu sunt actualizate

Process a delivery safely

1. Verificați semnătura utilizând anteturile și corpul cererii nedotate.
2. Parsează JSON-ul numai după ce verificarea este reușită.
3. Confirmă organizationId și eventType sunt cele așteptate de punctul tău final.
4. Înregistrați atomic eventId înainte de a produce efecte secundare. Ignorați un ID pe care l-ați procesat deja.
5. Verificați evenimentul și returnați un răspuns de succes.

Pentru evenimente de actualizare, comparați updatedFrom cu data pentru a identifica modificarea. ID-urile de resurse, cum ar fi un document sau ID-ul de utilizator, sunt încorporate în data; acestea nu sunt câmpuri rădăcină.

HTTP headers

Fiecare cerere poartă, de asemenea, metadate în anteturi.Unele antete reflectă câmpurile de înveliș rădăcină, astfel încât să puteți direcționa sau respinge o livrare înainte de analizarea corpului.

Header	Mirrors body field	Description
Content-Type	—	Always application/json
X-Probo-Webhook-Event	eventType	Wire-format event name (e.g. document:updated)
X-Probo-Webhook-Organization-Id	organizationId	Organization ID
X-Probo-Webhook-Timestamp	—	Unix timestamp in seconds utilizat la calcularea semnăturii
X-Probo-Webhook-Signature	—	HMAC-SHA256 codificat hex din {timestamp}:{rawBody}
X-Probo-Webhook-Host	—	Numele de gazdă al instantei platformei care a trimis livrarea (pentru receptorii multi-regiuni / auto-gazdă)

Header vs body

Use case	Prefer
Signature verification	Headers (X-Probo-Webhook-Timestamp, X-Probo-Webhook-Signature) + raw body bytes
Fast allow/deny before JSON parse	Headers (X-Probo-Webhook-Event, X-Probo-Webhook-Organization-Id, X-Probo-Webhook-Host)
Business logic / diffs	Root envelope + data / updatedFrom
Idempotency	Root eventId

subscriptionId și createdAt există numai în rădăcina corpului – ele nu sunt duplicate ca titluri.

Signing secret

platforma generează un secret de semnătură prefixat cu whsec_ pentru fiecare abonament. Stochează-l într-un manager secret, extinde-l la serviciul de primire și nu îl înregistrează niciodată sau îl includ în codul de partea clientului. Secretul este necesar pentru verify webhook signatures.

Delivery behavior

• platforma efectuează sondaje pentru evenimente în așteptare aproximativ la fiecare 5 secunde și le procesează secvențial.
• O livrare are loc numai atunci când punctul final returnează 200, 201, 202 sau 204 în decurs de 30 de secunde.
• Failed deliveries are not retried automatically.
• platforma stochează starea răspunsului, anteturile și până la 64 KB din corpul de răspuns pentru rezolvarea problemelor.
• Starea de livrare este PENDING, SUCCEEDED, sau FAILED.

Review delivery history under Settings > WebhooksEvitați să returnați secrete sau înregistrări sensibile în corpul dvs. de răspuns, deoarece răspunsul este reținut pentru debugging.

Nu depinde de webhook ca singura copie a datelor

Deoarece livrările eșuate nu sunt reluate, utilizați webhooks ca notificări de schimbare. Dacă pierderea unui eveniment ar fi critică, reconciliați periodic starea locală cu platformaAPI.

Receiver checklist

• Păstrați corpul crud până când verificarea semnăturii este completă.
• Acceptați solicitări numai de la organizațiile și tipurile de evenimente așteptate.
• Utilizați eventId pentru a face procesarea idempotent.
• Coada de lucru înainte de a trimite răspunsul.
• Alertă cu privire la livrările ___ZBT_I18N_RUNTIME_BLOCK_246__ și reconciliează modificările pierdute.
• Ignorați câmpurile JSON necunoscute, astfel încât modificările aditive ale sarcinii utile să nu întrerupă receptorul.

Next steps

Event Types Vezi toate evenimentele webhook disponibile și sarcinile lor

Signature Verification Verificați dacă solicitările webhook provin de pe platformă

n8n Trigger Începeți fluxurile de lucrun8ndin evenimentele webhook ale platformei