Webhooks Overview

Webhooks allows your application to react when resources change in the platform without asking for API. A subscription connects an HTTPS endpoint to a set of events in a single organization. When an event occurs, the platform sends a signed request POST containing a JSON instant image of the affected resource.

Common uses include synchronizing users and third parties, initiating document approval workflows, and recording compliance events in another system.

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 quorum approval events

Other product areas – including frameworks, controls, measures, risks, access reviews, devices and consent to cookies – are available through GraphQL, the CLI, MCP, and n8nUse surveys or a scheduled reconciliation task for those areas when your integration needs to remain current.

See Event types for the full reference of the load for the accepted events.

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

One delivery, from changing the platform to your recognition.

1. Expose an HTTPS endpoint

   Your endpoint must accept the requests POST with a body application/json.

2. Create a subscription

   In the platform, open Settings > Webhooks, enter the URL of the endpoint and select the events to be received.You can also manage subscriptions with CLI.

3. Verify every delivery

   Check your signature against the gross application body and reject stagnant timestamps before parsing or acting on the useful load.

4. Acknowledge quickly

   The answer is 2xx The answer is 2xx .

Endpoint requirements

• The URL must use HTTPS.
• The end point must return 200, 201, 202 or 204.
• The complete response must arrive within 30 seconds.

Any other state, connection error or timing marks the delivery as failed. the platform does not re-analyze failed deliveries, so it monitors the delivery history and designs a recovery process for missed events.

Root envelope

Resource-specific fields live under ___ZBT_I18N_RUNTIME_BLOCK_187__ (and optional updatedFrom) – they are never promoted to the root.

{
  "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	Unique delivery ID. Use it as an idempotency key
subscriptionId	string	Yes	Abonamentul Webhook care a primit evenimentul
organizationId	string	Yes	Organization in which the event took place
eventType	string	Yes	Wire-format event name (e.g. document:updated, third-party:created)
createdAt	string	Yes	When the event was created (RFC 3339)
data	object	Yes	Shape depends on eventType — see Event Types
updatedFrom	object	No	Present only on events *:updated. Full image of the same resource form as data, taken before updating. Omitted for creating, deleting, archiving, signing and other events that are not updated

Process a delivery safely

1. Verify the signature using the headers and body of the undoted application.
2. Parse the JSON only after the verification is successful.
3. Confirm organizationId and eventType are the ones expected by your end point.
4. Atomically register eventId before it produces side effects. Ignore an ID that you have already processed.
5. Check the event and return a successful response.

For update events, compare updatedFrom with data to identify the change. Resource IDs, such as a document or user ID, are embedded in data; these are not root fields.

HTTP headers

Each application also carries metadata in headers.Some headers reflect the root cover fields so you can direct or reject a delivery before analysing the body.

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 used to calculate the signature
X-Probo-Webhook-Signature	—	HMAC-SHA256 hex coded from {timestamp}:{rawBody}
X-Probo-Webhook-Host	—	Host name of the instance of the platform that sent the delivery (for multi-region / self-host receivers)

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 only in the root of the body – they are not duplicated as titles.

Signing secret

The platform generates a prefixed signature secret with whsec_ for each subscription. Store it in a secret manager, extend it to the receiving service and never register it or include it in the customer side code. verify webhook signatures.

Delivery behavior

• The platform conducts surveys for pending events approximately every 5 seconds and processes them sequentially.
• A delivery only occurs when the end point returns 200, 201, 202 or 204 within 30 seconds.
• Failed deliveries are not retried automatically.
• The platform stores the response status, headers and up to 64 KB of the response body for troubleshooting.
• The delivery status is PENDING, SUCCEEDED, or FAILED.

Review delivery history under Settings > WebhooksAvoid returning secrets or sensitive records into your response body as the response is retained for debugging.

It does not depend on the webhook as the only copy of the data

Since failed deliveries are not repeated, use webhooks as change notifications. If the loss of an event would be critical, periodically reconcile the local state with the API platform.

Receiver checklist

• Keep the body raw until the signature check is complete.
• Accept requests only from organizations and expected event types.
• Use eventId to make processing idempotent.
• Work the queue before sending the answer.
• Alerts about deliveries ___ZBT_I18N_RUNTIME_BLOCK_246__ and reconciles lost changes.
• Ignore unknown JSON fields so that additive changes to the useful load do not disrupt the receiver.

Next steps

Event Types View all available webhook events and their tasks

Signature Verification Check if webhook requests come from the platform

n8n Trigger Start workflows8ndin platform webhook events