What do I need before I connect Stripe?#
You need a Stripe account and access to its Developers area. Stripe gives you two values Agent Studio uses: a secret key (or a restricted key) that starts with sk_live_ or rk_live_, and a webhook signing secret that starts with whsec_. Test keys that start with sk_test_ work the same way while you rehearse.
| Header name | Value | What it does |
|---|---|---|
authorization | Bearer sk_live_... (or rk_live_...) | Lets Agent Studio open checkouts and manage subscriptions on your account |
x-suede-stripe-webhook-secret | whsec_... | Proves each payment notice really came from Stripe |
How do I connect my Stripe account?#
You connect Stripe in four moves across Connections, Payment settings and your Stripe dashboard. Keep both tabs open and it takes a few minutes.
Connect Stripe to Suede AI Agent Studio
Step 1: Create the Stripe connection
In Connections, choose Any API and press Add an API. Name itOpen ConnectionsStripe, set Sign-in method to Custom headers and enter the header namesauthorization, x-suede-stripe-webhook-secret. Add the values one per line in that order:Bearer sk_live_...first. Leave the second line for the signing secret you get in step 3.Step 2: Choose it in Payment settings
Open Payments, then Settings. Under Your Stripe account, pick your connection in Stripe connection and press Save. Saving creates your private webhook URL.Open Payment settingsStep 3: Add the webhook in Stripe
Press Copy URL in the Webhook panel. In Stripe, open Developers, then Webhooks, add an endpoint with that URL and select the events listed under Events to send. Stripe then shows the endpoint'swhsec_...signing secret.Step 4: Save the signing secret
Back in Connections, add theOpen Connectionswhsec_...value as thex-suede-stripe-webhook-secretline on your Stripe connection, so every payment is confirmed in Agent Studio.Step 5: Test the connection
In Payment settings press Test connection. Agent Studio reads your Stripe account and reports its name, its id and whether it is in live mode or test mode.Test connection
Which Stripe webhook events should I send?#
Send all eleven events listed in Payment settings. Together they confirm checkouts, card payments, subscription renewals, cancellations and refunds.
checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
payment_intent.succeeded
payment_intent.payment_failed
invoice.paid
invoice.payment_failed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
charge.refundedHow does Agent Studio protect my Stripe keys?#
Your keys live in an encrypted connection on the server and never appear in CRM records, pay pages or the browser. Payment settings shows connection names and whether each one carries the right headers, never the values. Every webhook delivery is checked against your signing secret before Agent Studio acts on it.
What do I do if the test does not pass?#
| Message | Fix |
|---|---|
| This connection has no authorization header. | Add authorization to the header names on the connection, with Bearer sk_live_... as its value. |
| Add the x-suede-stripe-webhook-secret header | Create the webhook in Stripe, then add its whsec_... secret to the connection. |
| Stripe has not turned on charges for this account yet. | Finish your business details in Stripe so it activates card charges. |
| No events from Stripe yet. | Check the endpoint URL in Stripe matches Copy URL and that the events are selected. |
Need a fresh webhook URL? Press New URL. The old one stops working at once, so paste the new one into Stripe right after.