> ## Documentation Index > Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Replace Webhook > Replaces the webhook with the one sent: send every field, as an omitted field is cleared ## OpenAPI ````yaml v2/api-reference/openapi.json PUT /v2/webhooks/{webhook_id} openapi: 3.0.0 info: title: Trio API v2 version: 2026-10-19.v2 servers: - url: https://api.sandbox.trio.com.br variables: {} - url: https://api.qa.trio.com.br variables: {} - url: https://api.trio.com.br variables: {} security: [] tags: [] paths: /v2/webhooks/{webhook_id}: parameters: - description: >- Version of the v2 contract the client is written against. Each breaking change publishes a new version. example: 2026-10-19.v2 in: header name: Trio-Version required: true schema: enum: - 2026-10-19.v2 type: string x-struct: null x-validate: null - description: >- ID of another org to act on instead of the API key's own org. The key's org must have been granted access to it, and the request is refused with 403 FORBIDDEN otherwise. When that access or the API key is read-only, only GET and HEAD requests may carry it. When the target org requires mTLS, so does the request. Leave it out to act on the key's own org. in: header name: Trio-Target-Org-Id required: false schema: format: uuid type: string x-struct: null x-validate: null put: tags: - Webhooks summary: Replace org webhook description: >- Replaces the webhook with the one sent: send every field, as an omitted field is cleared operationId: TrioFoundationWeb.V2.IAM.OrgWebhookController.update parameters: - description: Webhook ID in: path name: webhook_id required: true schema: $ref: '#/components/schemas/UUID' requestBody: content: application/json: schema: $ref: '#/components/schemas/V2_Org_webhook_update_parameters' description: Org webhook update parameters required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/V2_Org_webhook_response' description: Updated webhook '400': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: >- Malformed request: a body that is not valid JSON (MALFORMED_REQUEST), or a Trio-Version header that is missing or not the current one (INVALID_TRIO_VERSION). '401': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: Missing or invalid API key credentials (INVALID_CREDENTIALS). '403': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: >- The API key may not do this (FORBIDDEN): for instance Trio-Target-Org-Id names an org it has no access to, or writes through a read-only access. '404': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: No resource with this ID (NOT_FOUND_RESOURCE). '422': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: >- Invalid input (INVALID_PARAMETER, REQUIRED_PARAMETER, or the code of the rule the request breaks). A request outside the operation's schema lists the offending fields in `errors`. '503': content: application/json: schema: $ref: '#/components/schemas/V2_error' description: >- A service needed to answer is unavailable (TRIO_SERVICE_UNAVAILABLE). callbacks: {} security: - authorization: [] components: schemas: UUID: description: Unique identifier format: uuid title: UUID type: string x-struct: null x-validate: null V2_Org_webhook_update_parameters: description: >- The webhook replacing the current one: send every field, as an omitted field is cleared. A url_secret webhook needs notification_url and notification_secret; an oauth webhook needs oauth_client_id, oauth_client_secret, oauth_url and oauth_scope. example: api_version: v100 authentication_method: url_secret entity_id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c event_categories_allowed: - category: boleto types: - settled - created group_id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7d notification_secret: some_notification_secret notification_url: https://mynotificationurl.com/endpoint properties: api_version: description: Version of the event payloads sent to the webhook. Defaults to v100 enum: - v100 - v200 nullable: true type: string x-struct: null x-validate: null authentication_method: description: How Trio authenticates to the notification URL enum: - url_secret - oauth type: string x-struct: null x-validate: null entity_id: description: >- Entity to limit the webhook to. Omitted, the webhook is no longer limited format: uuid nullable: true type: string x-struct: null x-validate: null event_categories_allowed: description: >- Events to send to the webhook. Empty, null or omitted sends every event items: properties: category: description: Event category type: string x-struct: null x-validate: null types: description: Event types of the category. Empty sends every type items: type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - category - types type: object x-struct: null x-validate: null nullable: true type: array x-struct: null x-validate: null group_id: description: >- Group of the entity to limit the webhook to. Omitted, the webhook is no longer limited format: uuid nullable: true type: string x-struct: null x-validate: null notification_secret: description: Secret sent with every event, for url_secret webhooks nullable: true type: string x-struct: null x-validate: null notification_url: description: URL the events are sent to type: string x-struct: null x-validate: null oauth_client_id: description: OAuth client ID nullable: true type: string x-struct: null x-validate: null oauth_client_secret: description: OAuth client secret nullable: true type: string x-struct: null x-validate: null oauth_scope: description: OAuth scope nullable: true type: string x-struct: null x-validate: null oauth_url: description: OAuth token URL nullable: true type: string x-struct: null x-validate: null required: - notification_url - authentication_method title: V2 Org webhook update parameters type: object x-struct: Elixir.TrioFoundationWeb.Schemas.IAM.V2.OrgWebhook.UpdateParameters x-validate: null V2_Org_webhook_response: description: A webhook the org receives its events at example: data: api_version: v100 authentication_method: url_secret entity_id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c event_categories_allowed: - category: boleto types: - settled - created group_id: null id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b inserted_at: '2026-10-01T12:00:00.000000Z' notification_key: KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ== notification_secret: some_notification_secret notification_url: https://mynotificationurl.com/endpoint updated_at: '2026-10-01T12:00:00.000000Z' properties: data: $ref: '#/components/schemas/V2_Org_webhook' title: V2 Org webhook response type: object x-struct: Elixir.TrioFoundationWeb.Schemas.IAM.V2.OrgWebhook.Response x-validate: null V2_error: example: error: error_code: INVALID_PARAMETER error_message: 'Invalid parameters: /amount: Invalid integer. Got: string' errors: - field: /amount message: 'Invalid integer. Got: string' properties: error: properties: error_code: description: >- Stable UPPER_SNAKE identifier of the error, for programs and logs. Branch on this, not on the message. type: string x-struct: null x-validate: null error_message: description: Human readable explanation of the error. type: string x-struct: null x-validate: null errors: description: >- Only on INVALID_PARAMETER for a request outside the operation's schema: one entry per offending field. items: properties: field: description: JSON pointer to the field, e.g. /amount. type: string x-struct: null x-validate: null message: description: What is wrong with it. type: string x-struct: null x-validate: null required: - field - message type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - error_code - error_message type: object x-struct: null x-validate: null required: - error title: V2 error type: object x-struct: Elixir.TrioFoundationWeb.Schemas.HTTP.V2Error x-validate: null V2_Org_webhook: description: A webhook the org receives its events at example: api_version: v100 authentication_method: url_secret entity_id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7c event_categories_allowed: - category: boleto types: - settled - created group_id: null id: 019a1c2e-5b7d-7f80-9a1b-2c3d4e5f6a7b inserted_at: '2026-10-01T12:00:00.000000Z' notification_key: KXe1JxmdHIcRhAsnbaTBvSGNSQli4I798oGMb8abeMBcKzJoUpWkOQ== notification_secret: some_notification_secret notification_url: https://mynotificationurl.com/endpoint updated_at: '2026-10-01T12:00:00.000000Z' properties: api_version: description: Version of the event payloads sent to the webhook enum: - v100 - v200 type: string x-struct: null x-validate: null authentication_method: description: How Trio authenticates to the notification URL enum: - url_secret - oauth type: string x-struct: null x-validate: null entity_id: description: Entity the webhook is limited to format: uuid nullable: true type: string x-struct: null x-validate: null event_categories_allowed: description: Events sent to the webhook. Empty or null sends every event items: properties: category: description: Event category type: string x-struct: null x-validate: null types: description: Event types of the category. Empty sends every type items: type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null type: object x-struct: null x-validate: null nullable: true type: array x-struct: null x-validate: null group_id: description: Group the webhook is limited to format: uuid nullable: true type: string x-struct: null x-validate: null id: description: Webhook ID format: uuid type: string x-struct: null x-validate: null inserted_at: description: When the webhook was created format: date-time type: string x-struct: null x-validate: null notification_key: description: >- Key Trio signs the events with, generated when the webhook is created type: string x-struct: null x-validate: null notification_secret: description: Secret sent with every event, for url_secret webhooks nullable: true type: string x-struct: null x-validate: null notification_url: description: URL the events are sent to nullable: true type: string x-struct: null x-validate: null updated_at: description: When the webhook was last updated format: date-time type: string x-struct: null x-validate: null title: V2 Org webhook type: object x-struct: Elixir.TrioFoundationWeb.Schemas.IAM.V2.OrgWebhook.WebhookData x-validate: null securitySchemes: authorization: scheme: basic type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.