> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Register a realm webhook > Registers a realm-wide webhook: one URL, subscribed to the given events, which it receives for every organization of the realm. It is an upsert: registering a URL that already exists adds the new events to it (an event it already has is re-activated) and replaces its headers when the request carries them. Nothing is ever duplicated or deleted. Only realm admins can call this. Answers the webhook with every event it is now subscribed to. ## OpenAPI ````yaml /api-reference/notification.openapi.json post /realms/{realmId}/webhooks openapi: 3.0.3 info: title: Notification version: 1.0.0 description: >- Portão 3 notification API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Webhooks: register URLs, subscribe them to events, and activate or deactivate each event. Realm-wide webhooks (`/realms/{realmId}/webhooks`) receive the events of every organization of the realm and are managed by realm admins; organization webhooks are managed by the organization. Confidence tiers: generated:typed=12 copied:manual=0 unknown=0. servers: - url: https://api.notification.v2.portao3.com.br/ description: production - url: https://api.notification.dev.3pers.com.br/ description: development security: [] tags: - name: Webhooks paths: /realms/{realmId}/webhooks: post: tags: - Webhooks summary: Register a realm webhook description: >- Registers a realm-wide webhook: one URL, subscribed to the given events, which it receives for every organization of the realm. operationId: postRealmsByRealmIdWebhooks parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: >- Absolute HTTPS URL the events are POSTed to. The same URL registered twice is one webhook — registering it again adds events and replaces the headers. example: https://hooks.example.com/p3 headers: description: >- Headers to send on every delivery, e.g. an authorization token. When omitted, the headers already registered for the URL are kept. --- Example: `{"Authorization":"Bearer …"}` example: Authorization: Bearer … type: object additionalProperties: type: string events: minItems: 1 maxItems: 100 type: array items: type: object properties: source: type: string enum: - WALLET - BILLING - TRAVEL description: >- The area the event comes from: `WALLET` for the banking events (PIX, cards, wallets), `BILLING` for invoices, contracts and deals, `TRAVEL` for travel reservations. example: WALLET event: type: string minLength: 1 maxLength: 100 description: >- The event to subscribe to — one of the `source`'s events (see the Webhooks guide). example: PIX_IN required: - source - event additionalProperties: false description: >- The events to subscribe the URL to. A realm-wide webhook receives them for every organization of the realm. An event the URL already has is re-activated. required: - url - events additionalProperties: false responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: >- ID of the webhook. It is derived from the URL and the organization, so registering the same URL again returns the same webhook instead of a second one. example: 3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f format: uuid realmId: type: string description: ID of the realm the webhook belongs to. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: >- ID of the organization the webhook belongs to, or `*` for a realm-wide webhook, which receives the events of every organization of the realm. example: '*' url: type: string description: The URL every event is POSTed to. example: https://hooks.example.com/p3 headers: type: object additionalProperties: type: string description: |- Headers sent on every delivery, as registered. --- Example: `{"Authorization":"Bearer …"}` example: Authorization: Bearer … events: type: array items: type: object properties: id: type: string description: >- ID of the event. Use it in `…/webhooks/{webhookId}/events/{eventId}/activate` and `/deactivate`. example: 7f1b1c2e-2d3a-4b5c-9e8f-0a1b2c3d4e5f format: uuid source: type: string enum: - WALLET - SOLICITATION - SECURITY - USER - BILLING - CUSTOMER - TRAVEL - ROOT - RULE_ENGINE - SCHEDULING description: The area the event comes from. example: WALLET event: type: string description: >- The event name (see the Webhooks guide for the list and each payload). A plain string, not an enum: a subscription made before an event was retired still lists that event's name, so a client must not reject an unknown value here. example: PIX_IN status: type: string enum: - ACTIVE - INACTIVE description: >- `ACTIVE`: the webhook receives this event. `INACTIVE`: it does not, until it is activated again. example: ACTIVE createdAt: type: string description: >- When this event was first subscribed to in the webhook's scope — by any webhook of the scope, so it can predate this webhook's own subscription to it. example: '2026-10-02T14:03:11.000Z' required: - id - source - event - status description: >- One event the webhook is subscribed to, and whether it is currently delivered. description: >- Every event the webhook is subscribed to, with its status. Sorted by event name. createdAt: type: string description: When the webhook was registered. example: '2026-10-01T09:30:00.000Z' updatedAt: type: string description: When the webhook was last changed. example: '2026-10-02T14:03:11.000Z' required: - id - realmId - organizationId - url - headers - events description: >- A webhook: one URL that receives events, with the headers sent on every delivery. '403': description: >- `NOTIFICATION_REALM_ADMIN_REQUIRED` — You are not an admin of the realm. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - NOTIFICATION_REALM_ADMIN_REQUIRED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - NOTIFICATION description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: NOTIFICATION_REALM_ADMIN_REQUIRED origin: NOTIFICATION message: Realm admin required '422': description: >- `BAD_REQUEST` — The body is invalid — a URL that does not parse, no `events`, an event its source does not emit, or a field this route does not take (such as `organizationId`); `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - NOTIFICATION description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: NOTIFICATION message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: url message: 'Invalid input: expected string, received undefined' code: URL_REQUIRED ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.