# 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](/docs/developers/graphql), the [CLI](/docs/developers/cli/overview), [MCP](/docs/developers/api/mcp/overview), or [n8n](/docs/developers/api/n8n/overview) for those domains, and poll or reconcile when your integration must stay current.

See [Event types](/docs/developers/api/webhooks/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

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](/docs/developers/api/webhooks/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](/docs/developers/graphql).

The [quickstart](/docs/developers/api/webhooks/quickstart) walks through that path with complete Go, Python, and TypeScript handlers.

Manage subscriptions in **Settings > Webhooks**, with [`prb webhook`](/docs/developers/cli/commands/webhook), with the [MCP webhook tools](/docs/developers/api/mcp/tools/catalog/webhooks), or from [n8n](/docs/developers/api/n8n/trigger). Programmatic create and update require the `v1:webhook` OAuth scope and permission to manage subscriptions in the organization.

## Next steps

- [Quickstart](/docs/developers/api/webhooks/quickstart) — Stand up a receiver, create a subscription, and confirm a delivery
- [Signature verification](/docs/developers/api/webhooks/signature-verification) — Verify HMAC-SHA256 signatures on the raw request body
- [Event types](/docs/developers/api/webhooks/event-types) — Look up wire names, API enums, and payload schemas
- [Delivery and recovery](/docs/developers/api/webhooks/delivery-and-recovery) — Handle retries, idempotency, failed jobs, and secret rotation