{ "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" } ], "x-p3-surface": "public", "tags": [ { "name": "Webhooks" } ], "components": {}, "paths": { "/realms/{realmId}/webhooks": { "get": { "operationId": "getRealmsByRealmIdWebhooks", "summary": "List realm webhooks", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 1, "description": "Lists the realm-wide webhooks — the ones registered for every organization of the realm (`organizationId` is `*`), newest first. An organization's own webhooks are listed through `GET /realms/{realmId}/organizations/{organizationId}/webhooks`.", "x-mint": { "content": "Each webhook comes with every event it is subscribed to and whether that event is currently delivered (`status`). Filter by `events` (comma-separated) and page with `limit` + `next`.\n\nOnly realm admins can call this." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "events", "in": "query", "required": false, "description": "Only the webhooks subscribed to at least one of these events, whatever the subscription's status. Each webhook still lists every event it is subscribed to.\n\n---\n\nExample (comma-separated list): `?events=PIX_IN,PIX_OUT`", "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "style": "form", "explode": false }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100. Defaults to 15.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "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.\n\n---\n\nExample: `{\"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." }, "description": "Webhooks, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of webhooks." } } } }, "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` — A path or query parameter is invalid; `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": "events", "message": "Too big: expected array to have <=100 items", "code": "EVENTS_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdWebhooks", "summary": "Register a realm webhook", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 2, "description": "Registers a realm-wide webhook: one URL, subscribed to the given events, which it receives for every organization of the realm.", "x-mint": { "content": "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." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `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.\n\n---\n\nExample: `{\"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.\n\n---\n\nExample: `{\"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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/webhooks/{webhookId}/events/{eventId}/activate": { "post": { "operationId": "postRealmsByRealmIdWebhooksByWebhookIdEventsByEventIdActivate", "summary": "Activate a realm webhook event", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 3, "description": "Turns one event of a realm-wide webhook back on: its `status` becomes `ACTIVE` and the webhook receives the event again. Idempotent — an already active event is returned unchanged. No request body. Only realm admins can call this.", "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "webhookId", "in": "path", "required": true, "description": "ID of the realm-wide webhook (`id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f" }, { "name": "eventId", "in": "path", "required": true, "description": "ID of the event (`events[].id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f1b1c2e-2d3a-4b5c-9e8f-0a1b2c3d4e5f" } ], "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.\n\n---\n\nExample: `{\"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" } } } }, "404": { "description": "`WEBHOOK_NOT_FOUND` — No realm-wide webhook with this ID exists in the realm.\n\n`WEBHOOK_EVENT_NOT_FOUND` — The webhook is not subscribed to an event with this ID.", "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": [ "WEBHOOK_NOT_FOUND", "WEBHOOK_EVENT_NOT_FOUND" ], "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": "WEBHOOK_NOT_FOUND", "origin": "NOTIFICATION", "message": "Webhook not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "eventId", "message": "Invalid UUID", "code": "EVENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/webhooks/{webhookId}/events/{eventId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdWebhooksByWebhookIdEventsByEventIdDeactivate", "summary": "Deactivate a realm webhook event", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 4, "description": "Turns one event of a realm-wide webhook off: its `status` becomes `INACTIVE` and the webhook stops receiving the event until it is activated again (or re-registered). The webhook itself and its other events are untouched. Idempotent. No request body. Only realm admins can call this.", "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "webhookId", "in": "path", "required": true, "description": "ID of the realm-wide webhook (`id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f" }, { "name": "eventId", "in": "path", "required": true, "description": "ID of the event (`events[].id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f1b1c2e-2d3a-4b5c-9e8f-0a1b2c3d4e5f" } ], "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.\n\n---\n\nExample: `{\"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": "INACTIVE" }, "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" } } } }, "404": { "description": "`WEBHOOK_NOT_FOUND` — No realm-wide webhook with this ID exists in the realm.\n\n`WEBHOOK_EVENT_NOT_FOUND` — The webhook is not subscribed to an event with this ID.", "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": [ "WEBHOOK_NOT_FOUND", "WEBHOOK_EVENT_NOT_FOUND" ], "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": "WEBHOOK_NOT_FOUND", "origin": "NOTIFICATION", "message": "Webhook not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "eventId", "message": "Invalid UUID", "code": "EVENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/webhooks": { "get": { "operationId": "getRealmsByRealmIdOrganizationsByOrganizationIdWebhooks", "summary": "List organization webhooks", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 5, "description": "Lists the organization's webhooks, newest first. Realm-wide webhooks also receive the organization's events but are not listed here — see `GET /realms/{realmId}/webhooks`.", "x-mint": { "content": "Each webhook comes with every event it is subscribed to and whether that event is currently delivered (`status`). Filter by `events` (comma-separated) and page with `limit` + `next`." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization whose webhooks you want to list.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "events", "in": "query", "required": false, "description": "Only the webhooks subscribed to at least one of these events, whatever the subscription's status. Each webhook still lists every event it is subscribed to.\n\n---\n\nExample (comma-separated list): `?events=PIX_IN,PIX_OUT`", "schema": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "style": "form", "explode": false }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1–100. Defaults to 15.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "example": 15 }, { "name": "next", "in": "query", "required": false, "description": "Cursor returned as `next` by the previous page. Omit for the first page.", "schema": { "type": "string" }, "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "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": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "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.\n\n---\n\nExample: `{\"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." }, "description": "Webhooks, newest first." }, "next": { "type": "string", "nullable": true, "description": "Cursor for the next page. `null` on the last page.", "example": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy" } }, "required": [ "items", "next" ], "description": "A page of webhooks." } } } }, "422": { "description": "`BAD_REQUEST` — A path or query parameter is invalid; `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": "events", "message": "Too big: expected array to have <=100 items", "code": "EVENTS_MAX" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "parameters": "generated:typed" } }, "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdWebhooks", "summary": "Register an organization webhook", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 6, "description": "Registers a webhook for the organization: one URL, subscribed to the given events.", "x-mint": { "content": "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. Answers the webhook with every event it is now subscribed to." }, "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the webhook belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" } ], "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.\n\n---\n\nExample: `{\"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. 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": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "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.\n\n---\n\nExample: `{\"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." } } } }, "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; `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" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed", "request": "generated:typed", "note": "`.superRefine(…)` constraint not represented (runtime-dependent value)" } } }, "/realms/{realmId}/organizations/{organizationId}/webhooks/{webhookId}/events/{eventId}/activate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdWebhooksByWebhookIdEventsByEventIdActivate", "summary": "Activate an organization webhook event", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 7, "description": "Turns one event of an organization's webhook back on: its `status` becomes `ACTIVE` and the webhook receives the event again. Idempotent — an already active event is returned unchanged. No request body.", "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the webhook belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "webhookId", "in": "path", "required": true, "description": "ID of the webhook (`id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f" }, { "name": "eventId", "in": "path", "required": true, "description": "ID of the event (`events[].id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f1b1c2e-2d3a-4b5c-9e8f-0a1b2c3d4e5f" } ], "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": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "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.\n\n---\n\nExample: `{\"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." } } } }, "404": { "description": "`WEBHOOK_NOT_FOUND` — No webhook with this ID exists in the organization.\n\n`WEBHOOK_EVENT_NOT_FOUND` — The webhook is not subscribed to an event with this ID.", "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": [ "WEBHOOK_NOT_FOUND", "WEBHOOK_EVENT_NOT_FOUND" ], "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": "WEBHOOK_NOT_FOUND", "origin": "NOTIFICATION", "message": "Webhook not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "eventId", "message": "Invalid UUID", "code": "EVENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } }, "/realms/{realmId}/organizations/{organizationId}/webhooks/{webhookId}/events/{eventId}/deactivate": { "post": { "operationId": "postRealmsByRealmIdOrganizationsByOrganizationIdWebhooksByWebhookIdEventsByEventIdDeactivate", "summary": "Deactivate an organization webhook event", "tags": [ "Webhooks" ], "x-p3-sidebar-order": 8, "description": "Turns one event of an organization's webhook off: its `status` becomes `INACTIVE` and the webhook stops receiving the event until it is activated again (or re-registered). The webhook itself and its other events are untouched. Idempotent. No request body.", "parameters": [ { "name": "realmId", "in": "path", "required": true, "description": "ID of your realm.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b" }, { "name": "organizationId", "in": "path", "required": true, "description": "ID of the organization the webhook belongs to.\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, { "name": "webhookId", "in": "path", "required": true, "description": "ID of the webhook (`id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f" }, { "name": "eventId", "in": "path", "required": true, "description": "ID of the event (`events[].id` in the webhook list).\n\nFormat: `UUID`", "schema": { "type": "string", "format": "uuid" }, "example": "7f1b1c2e-2d3a-4b5c-9e8f-0a1b2c3d4e5f" } ], "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": "c4bd3f21-dfbd-44e8-8055-68ba15bed410" }, "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.\n\n---\n\nExample: `{\"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": "INACTIVE" }, "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." } } } }, "404": { "description": "`WEBHOOK_NOT_FOUND` — No webhook with this ID exists in the organization.\n\n`WEBHOOK_EVENT_NOT_FOUND` — The webhook is not subscribed to an event with this ID.", "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": [ "WEBHOOK_NOT_FOUND", "WEBHOOK_EVENT_NOT_FOUND" ], "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": "WEBHOOK_NOT_FOUND", "origin": "NOTIFICATION", "message": "Webhook not found" } } } }, "422": { "description": "`BAD_REQUEST` — A path parameter is not a valid ID; `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": "eventId", "message": "Invalid UUID", "code": "EVENTID_UUID" } ] } } } } }, "x-p3-confidence": { "response": "generated:typed" } } } } }