Read Stripe webhook secret

capability_id: stripe.webhook.read
display_name: Read Stripe webhook secret
ui_capability_key: read_stripe_webhook_secret
scope: stripe:webhook:read
endpoint:
  method: POST
  path: /stripe/webhook-secret
operation: stripe.webhook_secret.read
billable: true
environments:
  - production
  - staging
  - development

Purpose and authorization

This capability lets an authenticated application retrieve its Gateman-managed Stripe webhook signing secret for one supported environment. It is intended for applications that receive Stripe webhook requests and verify their signatures locally.

The application must be granted stripe:webhook:read. Gateman authenticates the application and enforces the shared Contract v1 request and application-isolation rules before serving the read. This capability is separate from stripe:webhook:write, which controls webhook endpoint setup and configuration.

Implementation contract

Request

POST /stripe/webhook-secret
Content-Type: application/json
X-GM-App: app_example
X-GM-Ts: 1791748800
X-GM-Sig: <Contract-v1-signature>
X-GM-Idempotency-Key: optional-gateman-key

The JSON request body is:

{
  "environment": "production"
}

The JSON body accepts exactly one field, environment. Supported values are production, staging, and development. The value is normalized according to the shared environment contract. Unknown values, a missing value, malformed JSON, or additional fields are rejected with a client error.

The environment selects the stored application-scoped value as follows:

Environment	Stored value
`production`	`STRIPE_WEBHOOK_SECRET`
`staging`	`STRIPE_WEBHOOK_SECRET_TEST`
`development`	`STRIPE_WEBHOOK_SECRET_TEST`

Response

Successful retrieval returns JSON containing the signing secret:

{
  "ok": true,
  "webhook_secret": "whsec_example_redacted"
}

The response is application-scoped and does not contain a Stripe webhook endpoint ID, endpoint metadata, event filters, or other Stripe resource data. Gateman does not call the Stripe API as part of this read.

Responses use JSON and include the shared request-correlation header. The response sends Cache-Control: no-store so browsers and HTTP intermediaries do not retain the response. A successful response is 200.

If the selected secret is not configured, the response is 404 with an error identifying that the Stripe webhook secret is not configured. If Gateman cannot retrieve the selected secret, the response is 503 with an unavailable error. Malformed or unsupported requests are 400; missing or insufficient authorization uses the shared authentication and authorization responses. Shared concurrency and operation-accounting failures use their documented response status and retry behavior, including Retry-After where applicable.

Operation accounting

Each admitted retrieval is accounted as one stripe.webhook_secret.read operation. Successful retrievals, and accepted reads that return missing-secret or retrieval-unavailable errors, each consume one operation. Requests rejected during authentication, validation, or admission do not consume an operation. Repeated accepted reads consume separate operations.

The operation is subject to shared application-level admission and monthly operation rules. Monthly allowance exhaustion and accounting unavailability retain their documented behavior. It does not use provider-bound concurrency admission because it does not make a Stripe provider request.

Idempotency

X-GM-Idempotency-Key, when used, is signed as part of the Contract v1 authentication material. This endpoint does not provide a general idempotency ledger, response replay, deduplication, or cache based on that header.

Secret handling

Treat the returned value as signing secret material. Do not place it in source code, logs, client-side code, browser storage, URLs, or error messages. Keep it within protected application-controlled configuration or memory, and limit access to the process that verifies Stripe webhook signatures.

Cache-Control: no-store controls HTTP response caching. The returned signing secret is sensitive credential material and must be protected from unauthorized disclosure, including through logs, browser code, URLs, or error messages.

Webhook verification and setup

The application receives webhook requests from Stripe and performs signature verification with the retrieved secret. Gateman does not receive the application’s webhook traffic, verify Stripe signatures for the application, deduplicate events, or manage payment state.

Webhook endpoint setup and configuration are a separate concern controlled by stripe:webhook:write. A read does not create, replace, delete, or update a Stripe webhook endpoint. A configured signing secret can change, and applications must use the current valid secret when verifying Stripe webhook signatures.

Official clients

The PHP, Node.js, Python, and Go clients support the shared authenticated request pattern. This capability has no dedicated client helper; applications call the capability endpoint and handle the returned secret according to their own protected configuration and webhook receiver design.

Data handling and retention

Gateman returns only the application-scoped signing secret selected by the request environment. The application is responsible for protecting it from unauthorized disclosure, controlling access and retention, verifying signatures, applying replay protection and event deduplication, and managing payment state.

Implementation outcome

A conforming independent integration authenticates with Contract v1, has the stripe:webhook:read scope, and calls POST /stripe/webhook-secret with the intended environment. It handles the documented success and error responses, protects the returned signing secret, and understands that each accepted read consumes one stripe.webhook_secret.read operation. The application verifies incoming Stripe webhook signatures itself; this read capability does not provision webhook endpoints or process webhook events.

Implementation instructions for agents

When implementing an application integration:

Grant only stripe:webhook:read when the application needs to retrieve its signing secret.
Call POST /stripe/webhook-secret for the intended application environment and handle the documented success and error responses.
Keep the returned signing secret protected and out of source, logs, client-side code, URLs, and user-visible errors.
Verify Stripe webhook signatures in the application’s webhook receiver and apply application-owned replay and event-deduplication controls.

Reusable AGENTS.md block

<!-- gateman:begin capability=stripe.webhook.read -->
# Read Stripe webhook secret

Use the `stripe.webhook.read` capability to retrieve the authenticated application's Gateman-managed Stripe webhook signing secret for one environment.

- Scope: `stripe:webhook:read`
- Endpoint: `POST /stripe/webhook-secret`
- Body: `{"environment":"production"}` using `production`, `staging`, or `development`
- Operation: `stripe.webhook_secret.read`
- Reference: https://docs.getgateman.com/capabilities/stripe.webhook.read/
- Required handling: keep the returned signing secret protected and out of logs, source, browser code, URLs, and user-visible errors.

The application verifies Stripe webhook signatures locally. Gateman does not receive the application's webhook traffic or manage event deduplication and payment state. Webhook endpoint setup is a separate `stripe:webhook:write` capability.
<!-- gateman:end capability=stripe.webhook.read -->