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’.
Autorizações
JWT bearer token issued by the identity provider.
Cabeçalhos
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.
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.
Parâmetros de caminho
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.
"BTG"

