Webhooks Overview

Webhooks permite aplicației dvs. să reacționeze atunci când resursele se schimbă în platformă, fără a apela la API. Un abonament conectează un endpoint HTTPS la un set de evenimente într-o singură organizație. POST solicitarea care conține o imagine JSON a resurselor afectate.

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:*, signature and approval quorum events

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

   Your endpoint must accept POST Cererea cu un application/json body.

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

   Persistați sau enqueeze evenimentul, apoi returnați un eveniment acceptat 2xx response. Perform slow work asynchronously.

Endpoint requirements

• The URL must use HTTPS.
• The endpoint must return 200, 201, 202, or 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

Fiecare corp de livrare este un obiect JSON cu un ambalaj rădăcină fix. data (and optionally updatedFromEle 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	Încărcătura efectivă a resurselor curente pentru eveniment. eventType — see Event Types
updatedFrom	object	No	Prezent doar pe *:updated Imaginea instantanee completă a aceleiași forme de resurse ca data, luate î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 and eventType Acestea sunt cele pe care punctul dvs. final le așteaptă.
4. Atomically record 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.

For update events, compare updatedFrom with data pentru a identifica modificarea. ID-urile de resurse, cum ar fi un document sau un ID de utilizator, sunt dataNu sunt câmpuri de 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	—	Hex-encoded HMAC-SHA256 of {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 and 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. Stocați-l într-un manager secret, extindeți-l la serviciul de primire și nu-l înregistrați niciodată sau includeți-l în codul de partea clientului. 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 reușită numai atunci când se întoarce punctul final 200, 201, 202, or 204 within 30 seconds.
• 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.
• Delivery status is PENDING, SUCCEEDED, or 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 vă bazați pe webhook ca pe 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 platforma API.

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.
• Use eventId to make processing idempotent.
• Coada de lucru înainte de a trimite răspunsul.
• Alert on FAILED deliveries and reconcile missed changes.
• 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 lucru n8n din evenimentele webhook ale platformei