Webhooks Overview

Webhooks let your application react when records change in Probo without polling. A subscription connects one HTTPS endpoint to a set of events in one organization. When a subscribed event occurs, Probo sends a signed POST request with a JSON snapshot of the affected resource.

Use webhooks to synchronize users and third parties, start document approval or signature workflows, and record privacy or compliance events in another system.

What webhooks cover

Domain	Event families
Third parties	third-party:*
Users	user:*
Obligations	obligation:*
Rights requests	right-request:*
Documents	document:*, document-version:*, signature and approval quorum events

Other product areas — including frameworks, controls, measures, risks, access reviews, devices, and cookie consent — do not emit webhook events. Use GraphQL, the CLI, MCP, or n8n for those domains, and poll or reconcile when your integration must stay current.

See Event types for every payload shape. Bodies and the X-Probo-Webhook-Event header use lowercase wire names such as user:created. The console, CLI, MCP, and n8n use uppercase enums such as USER_CREATED.

How delivery works

sequenceDiagram
  participant P as Probo
  participant E as Your endpoint

  Note over P: A subscribed resource changes
  P->>P: Enqueue a per-subscription delivery
  loop Until 2xx or the delivery is failed
    Note over P: Same eventId and JSON body. New timestamp and signature.
    P->>+E: POST signed JSON
    E->>E: Verify signature
    E->>E: Reject stale timestamp
    E->>E: Record eventId, enqueue
    alt 2xx within 15s
      E-->>-P: Success
    else Timeout, network error, 408, 425, 429, or 5xx
      E-->>P: Transient failure
      Note over P: Retry with backoff (honors Retry-After)
    else Other 4xx or attempts exhausted
      E-->>P: Terminal failure
    end
  end

A delivery from the change in Probo through retries until your endpoint accepts it or the job fails. Retries keep the same eventId and JSON body, and sign a fresh timestamp.

Each delivery is a durable job for one subscription:

• Probo sends POST with Content-Type: application/json over HTTPS.
• The body is a fixed root envelope (eventId, subscriptionId, organizationId, eventType, createdAt, data, and optional updatedFrom). Resource fields live under data.
• The request is HMAC-SHA256 signed. Verify the signature against the raw body before parsing JSON.
• A 2xx within 15 seconds is success. Transient failures retry automatically, up to 12 attempts. Non-retryable 4xx responses fail immediately.
• Retries reuse the same eventId and JSON body. Each attempt signs a new X-Probo-Webhook-Timestamp.
• Delivery is at-least-once. Concurrent sends and retries can arrive out of order. Treat webhooks as notifications, not as your system of record.

The envelope, headers, retry schedule, and recovery steps are in Delivery and recovery.

Build a receiver

1. Expose an HTTPS endpoint and create a narrowly scoped subscription. Copy the whsec_ signing secret when Probo shows it.
2. Verify every request, then parse the envelope and ignore duplicate eventId values.
3. Enqueue work and return 2xx before the 15-second timeout.
4. Alert on FAILED deliveries and reconcile missed changes with the Probo API.

The quickstart walks through that path with complete Go, Python, and TypeScript handlers.

Manage subscriptions in Settings > Webhooks, with prb webhook, with the MCP webhook tools, or from n8n. Programmatic create and update require the v1:webhook OAuth scope and permission to manage subscriptions in the organization.

Next steps

Quickstart Stand up a receiver, create a subscription, and confirm a delivery

Signature verification Verify HMAC-SHA256 signatures on the raw request body

Event types Look up wire names, API enums, and payload schemas

Delivery and recovery Handle retries, idempotency, failed jobs, and secret rotation