> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Revoke the tenant's inbound webhook connection for a provider > Cuts this tenant's inbound webhook channel for one provider, immediately and for every replica. Use it when a webhook URL or its signing key may have leaked. WHAT IS CUT: the tenant's current connection for the provider AND any previous connection still inside its rotation grace window. A rotation leaves the retired connection authenticating for a bounded window so the provider's in-flight retries are not lost; an incident severs both halves, so this operation does too. THE EFFECT IS IMMEDIATE AND NEEDS NO RESTART. Every delivery is authorized against the connection's current state, so the first delivery after this call answers 401 — there is no cache to expire and no window to wait out. revoked_connections reports how many connections were still able to serve a delivery and are not any more. ZERO IS A SUCCESS: it means nothing was live, because the channel was already cut or the tenant never connected. THE OPERATION IS IDEMPOTENT, AND WHAT THAT MEANS IS A REPLAY RATHER THAN A SECOND CUT. A retry carrying the SAME Idempotency-Key returns the stored answer of the first call for 48 hours without executing anything, which is what makes a call you never saw the answer to safe to repeat. It is also a trap mid-incident: if a provider connect ran between the two calls, the replay reports the first call's revoked_connections while the newly issued channel is still live — a 'cut' confirmation for a channel that is not cut. Send a FRESH Idempotency-Key whenever you need this call to cut again. THE ANSWER CARRIES NO CREDENTIAL — no connection token, no delivery URL and no signing key. Restoring the channel means calling provider connect again, which issues a NEW URL and a NEW signing key that must be registered at the provider. A provider_type this deployment does not serve is refused with 404, deliberately, rather than answered with a count of zero that would read as 'already cut'. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/admin/providers/webhooks/{provider_type}/cancel openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, installments, and queries; bill payments (bankslip, utilities, and DARF), cancellation, and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives in one of two shapes, and which one you get depends on where the service catches the failure. A failure that the request pipeline catches before the API layer sees it answers a flat JSON body on application/json; the idempotency check is the pipeline rule you meet most often. Authentication and authorization refusals follow the response contract documented by the operation. Everything the API layer catches answers an RFC 9457 problem document on application/problem+json. Read the media type to tell the two apart. The code member holds the same PBP-NNNN value in both, so branch on it. One pipeline refusal is not listed on the operations below: while a first request under the same idempotency key is still in flight, a retry is answered 409 with code PBP-0007 and the flat body. title: Payments — via BTG API version: 1.0.0 servers: - url: https://payments.sandbox.lerian.net security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: >- Issuing, querying and cancelling boletos, including installment series and the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying or cancelling those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/admin/providers/webhooks/{provider_type}/cancel: post: tags: - Admin summary: Revoke the tenant's inbound webhook connection for a provider description: >- Cuts this tenant's inbound webhook channel for one provider, immediately and for every replica. Use it when a webhook URL or its signing key may have leaked. WHAT IS CUT: the tenant's current connection for the provider AND any previous connection still inside its rotation grace window. A rotation leaves the retired connection authenticating for a bounded window so the provider's in-flight retries are not lost; an incident severs both halves, so this operation does too. THE EFFECT IS IMMEDIATE AND NEEDS NO RESTART. Every delivery is authorized against the connection's current state, so the first delivery after this call answers 401 — there is no cache to expire and no window to wait out. revoked_connections reports how many connections were still able to serve a delivery and are not any more. ZERO IS A SUCCESS: it means nothing was live, because the channel was already cut or the tenant never connected. THE OPERATION IS IDEMPOTENT, AND WHAT THAT MEANS IS A REPLAY RATHER THAN A SECOND CUT. A retry carrying the SAME Idempotency-Key returns the stored answer of the first call for 48 hours without executing anything, which is what makes a call you never saw the answer to safe to repeat. It is also a trap mid-incident: if a provider connect ran between the two calls, the replay reports the first call's revoked_connections while the newly issued channel is still live — a 'cut' confirmation for a channel that is not cut. Send a FRESH Idempotency-Key whenever you need this call to cut again. THE ANSWER CARRIES NO CREDENTIAL — no connection token, no delivery URL and no signing key. Restoring the channel means calling provider connect again, which issues a NEW URL and a NEW signing key that must be registered at the provider. A provider_type this deployment does not serve is refused with 404, deliberately, rather than answered with a count of zero that would read as 'already cut'. operationId: revokeProviderWebhookConnection parameters: - description: >- Tenant organization ID. Accepted but ignored: the tenant is determined by the credentials you authenticate with, so sending this header, or sending a different value in it, changes nothing. in: header name: X-Organization-Id schema: description: >- Tenant organization ID. Accepted but ignored: the tenant is determined by the credentials you authenticate with, so sending this header, or sending a different value in it, changes nothing. type: string - description: >- Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012. in: header name: Idempotency-Key schema: description: >- Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012. type: string - description: >- Provider whose inbound webhook channel is being cut, for example BTG. Matched case-insensitively; a provider this deployment does not serve is refused with 404 rather than answered with a count of zero. in: path name: provider_type required: true schema: description: >- Provider whose inbound webhook channel is being cut, for example BTG. Matched case-insensitively; a provider this deployment does not serve is refused with 404 rather than answered with a count of zero. examples: - BTG type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/RevokeWebhookConnectionResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- Authentication failed. Read the `Content-Type`: the authentication middleware answers `application/json` carrying error code `PBP-0003`, and the in-service identity gate further down the chain answers `application/problem+json` (RFC 9457). The content map also declares `text/plain`, which NOTHING in this service produces. Do not write a client branch for it. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' text/plain: schema: type: string description: >- The authenticated principal is not permitted to perform this action. Read the `Content-Type`: the authorization middleware answers `application/json` carrying error code `PBP-0004`, meaning the principal may not perform this ACTION at all. On POST /v1/payments and POST /v1/payments/darf a second shape is reachable — `application/problem+json` (RFC 9457) carrying `PBP-0209` — and it means the opposite thing about the action: the principal MAY perform it, and the signed-in end user is not the registered holder of the account the request names. Every other operation still has the single `PBP-0004` shape. The content map also declares `text/plain`, which NOTHING in this service produces. Do not write a client branch for it. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: Internal Server Error '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/PipelineError' security: - BearerAuth: [] components: schemas: RevokeWebhookConnectionResponse: additionalProperties: false properties: provider_type: type: string revoked_connections: format: int64 type: integer status: type: string required: - status - provider_type - revoked_connections type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object PipelineError: additionalProperties: false description: >- The flat error body. A failure caught before the API layer sees the request answers this shape on the application/json media type, instead of the RFC 9457 problem document. Read the media type to tell the two apart. The idempotency check is the rule that answers this way most often. properties: code: description: >- Stable, machine-readable error code, in the form PBP-NNNN. Branch on this value. It carries the same meaning as the code member of the problem document. examples: - PBP-0013 type: string details: additionalProperties: true description: Optional object carrying further facts about this occurrence. type: - object - 'null' message: description: A human-readable explanation specific to this occurrence. examples: - >- The request body does not match the original request for this idempotency key. type: string title: description: Short label for the condition. examples: - Idempotency Key Conflict type: string required: - code - title - message type: object ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````