# Webhooks Overview

Webhooks let your application react when resources change in the platform without polling the API. A subscription connects one HTTPS endpoint to a set of events in one organization. When an event occurs, the platform sends a signed `POST` request containing a JSON snapshot of the affected resource.

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 de produse – inclusiv cadre, controale, măsuri, riscuri, recenzii de acces, dispozitive și consimțământul pentru cookie-uri – sunt disponibile prin intermediul [GraphQL](/docs/developers/graphql), [CLI](/docs/developers/cli/overview), [MCP](/docs/developers/api/mcp/overview), și [n8n](/docs/developers/api/n8n/overview), dar acestea nu emit evenimente webhook astăzi.

Consultați [Tipuri de evenimente](/docs/developers/api/webhooks/event-types) pentru referința completă a sarcinii utile pentru evenimentele acceptate.

## How it works

1. **Expose an HTTPS endpoint**

   Your endpoint must accept `POST` requests with an `application/json` body.

2. **Create a subscription**

   În platformă, deschideți Settings > Webhooks**, introduceți URL-ul punctului final și selectați evenimentele care urmează să fie primite.De asemenea, puteți gestiona abonamentele cu [CLI](/docs/developers/cli/commands/webhook).

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**

   Persist or enqueue the event, then return an accepted `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

Every delivery body is a JSON object with a fixed root envelope. Resource-specific fields live under `data` (and optionally `updatedFrom`) — they are never promoted to the root.

```json
{
  "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            | Webhook subscription that received the event                                                                                                                                                 |
| `organizationId` | string | Yes            | Organization where the event occurred                                                                                                                                                        |
| `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            | Current resource payload for the event. Shape depends on `eventType` — see [Event Types](/docs/developers/api/webhooks/event-types)                                                          |
| `updatedFrom`    | object | No             | Present only on `*:updated` events. Full snapshot of the same resource shape as `data`, taken before the update. Omitted for create, delete, archive, signature, and other non-update events |

### Process a delivery safely

1. Verify the signature using the headers and untouched request body.
2. Parse the JSON only after verification succeeds.
3. Confirm `organizationId` and `eventType` are ones your endpoint expects.
4. Atomically record `eventId` before producing side effects. Ignore an ID you have already processed.
5. Enqueue 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 nested under `data`; they are not root fields.

## 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** used when computing the signature                                  |
| `X-Probo-Webhook-Signature`       | —                  | Hex-encoded HMAC-SHA256 of `{timestamp}:{rawBody}`                                               |
| `X-Probo-Webhook-Host`            | —                  | Hostname of the the platform instance that sent the delivery (for multi-region / self-hosted 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 body root — they are not duplicated as headers.

## Signing secret

the platform generates a signing secret prefixed with `whsec_` for each subscription. Store it in a secret manager, scope it to the receiving service, and never log it or include it in client-side code. The secret is required to [verify webhook signatures](/docs/developers/api/webhooks/signature-verification).

## Delivery behavior

- the platform polls for pending events approximately every 5 seconds and processes them sequentially.
- A delivery succeeds only when the endpoint 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.
- Delivery status is `PENDING`, `SUCCEEDED`, or `FAILED`.

Verificați istoricul de livrare în secțiunea Setări > Webhooks**. Evitați returnarea secretelor sau a înregistrărilor sensibile în corpul de răspuns, deoarece răspunsul este reținut pentru debugare.

:::precauție[Nu vă bazați pe webhook ca pe singura copie a datelor] Deoarece livrările nereușite nu sunt reluate, utilizați webhooks ca notificări de schimbare.

## Receiver checklist

- Preserve the raw body until signature verification is complete.
- Accept requests only from expected organizations and event types.
- Use `eventId` to make processing idempotent.
- Queue work before sending the response.
- Alert on `FAILED` deliveries and reconcile missed changes.
- Ignore unknown JSON fields so additive payload changes do not break your receiver.

## Next steps

- [Tipuri de evenimente](/docs/developers/api/webhooks/event-types) — Vedeți toate evenimentele webhook disponibile și sarcinile lor utile - [Verificare semnătură](/docs/developers/api/webhooks/signature-verification) — Verificați că solicitările webhook provin de pe platformă - [n8nTrigger](/docs/developers/api/n8n/trigger) — Începeți fluxurile de lucrun8nde pe platformă