> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Set Gateway Webhook Secret > Store the webhook signing secret on the workspace's active gateway connection without changing its id or per-connection webhook URL. This is the second half of a two-step connect: [Connect a Gateway](/api-reference/gateways/connect) with the API keys, create the webhook endpoint in the gateway console using the per-connection URL, then paste the secret it issues here. `provider` accepts `stripe`, `razorpay`, or `gocardless` — the same set as [Connect a Gateway](/api-reference/gateways/connect), even though the playground's provider list shows only the first two. The connection id — and therefore its webhook URL — is unchanged. The secret is sealed at rest and never returned; [List Gateway Connections](/api-reference/gateways/list) only reports whether one is set. `webhook_secret` is not checked for presence: an empty string is accepted and clears the stored secret. ## Response ```json theme={null} { "status": "updated" } ``` A bare status object, not a `{data}` envelope. ## Errors | Status | Code | When | Fix | | ------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `400` | `validation_failed` | The body is not valid JSON | Send `{"webhook_secret": "..."}` | | `400` | `validation_failed` | `provider` in the path is not a supported gateway (message: `provider must be one of: stripe, razorpay, gocardless`) | Use the provider name shown by [List Gateway Connections](/api-reference/gateways/list) | | `400` | `validation_failed` | `webhook_secret` contains a non-ASCII or control character after leading/trailing whitespace and invisible zero-width, BOM, and non-breaking-space characters are stripped; an interior space is not stripped and is rejected by the same rule | Re-copy the secret from the provider dashboard | | `401` | `unauthorized` | Missing or invalid API key / session | Send `Authorization: Bearer $API_KEY` | | `403` | `forbidden` | The session user is not an owner or admin | Gateway secrets are money-path config — ask an owner/admin | | `404` | `not_found` | No active connection exists for that provider | [Connect a Gateway](/api-reference/gateways/connect) first | | `503` | `internal_error` | Credential vault unavailable (`GATEWAY_ENCRYPTION_KEY` not configured on the API) | Self-hosted: set `GATEWAY_ENCRYPTION_KEY` and restart | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml PUT /v1/gateway-connections/{provider}/webhook-secret openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/gateway-connections/{provider}/webhook-secret: put: tags: - Gateway Connections summary: Set the webhook signing secret on the active connection description: > Updates the webhook secret in place (id unchanged, so the per-connection webhook URL stays stable). Two-step connect: create the webhook in the gateway console using the per-connection URL, then paste the secret here. Owner/admin only. operationId: setGatewayWebhookSecret parameters: - name: provider in: path required: true schema: type: string enum: - stripe - razorpay requestBody: required: true content: application/json: schema: type: object properties: webhook_secret: type: string responses: '200': description: Updated. content: application/json: schema: type: object properties: status: type: string const: updated '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: responses: BadRequest: description: The request body or parameters are invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Authenticated but not permitted (insufficient role). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````