This article is intended for Administrators. Before you start, make sure you have:
- Administrator access to the platform, to edit the Payment integration settings.
- Access to your organisation's Stripe Dashboard with a role that can open the Developers area (webhooks and API keys).
- The webhook endpoint URL for your platform. Contact Support if you do not have it.
Stripe secret keys and signing secrets give access to your payment account. Only share them through the platform's Payment integration fields.
The Payment integration connects the platform to your Stripe account. It relies on two values for each mode (test and live):
a Stripe account API key, which lets the platform communicate with your Stripe account, and
a Stripe webhook signature, which lets the platform verify that payment events it receives really come from Stripe.
The setup follows these stages:
- 1Open the Developers area (Workbench) in Stripe
- 2Create or review the webhook event destination and its events
- 3Copy the destination's signing secret
- 4Copy your Stripe secret key
- 5Paste both values into the platform's Payment integration settings
- 6Check that events are delivered successfully
Repeat stages 2 to 5 for each mode you use: test values go into the Test fields, live values into the Live fields.
- Workbench: Stripe's developer area, which contains the Webhooks, Events, and Logs tabs.
- Event destination: the webhook endpoint (URL) to which Stripe sends events. Each destination has its own status, events, and signing secret.
-
Event: a notification Stripe sends when something happens in your account, for example
invoice.paid. -
Signing secret: the value starting with
whsec_, used by the platform to verify webhook requests. It is entered in the platform as the Stripe webhook signature. - Secret key: the Stripe standard key entered in the platform as the Stripe account API key. The Publishable key is not used here.
- Test mode / Live mode: Stripe keeps separate keys, secrets, and destinations for test (sandbox) and live payments.
| Value | Where to find it in Stripe | What it does | Platform fields |
|---|---|---|---|
| Secret key | Developers > API keys > Standard keys | Allows the platform to communicate with your Stripe account | Test / Live Stripe account API key |
Signing secret (whsec_…) |
Workbench > Webhooks > event destination details | Allows the platform to confirm that incoming events come from Stripe | Test / Live Stripe webhook signature |
I. Open the Developers area in Stripe
Go to: Stripe Dashboard > Developers > Webhooks.
- Sign in to your Stripe Dashboard and check that the correct account is selected at the top of the left-hand menu.
- Either type webhooks in the search bar and select Webhooks under Workbench, or open Developers at the bottom of the left-hand menu and select Webhooks.
Result: The Workbench opens on the Webhooks tab, showing the Event destinations list.
II. Create or review the event destination
Go to: Workbench > Webhooks > Event destinations.
The list shows each destination's URL, status (for example Active), number of events it listens to, event source, activity, response time, and error rate.
If no destination exists for your platform
- Click Add destination.
- Enter your platform's webhook endpoint URL.
- In the Events section, select the events listed in the table below.
- Complete the creation of the destination.
If a destination already exists
Click the menu at the end of its row to access:
- Edit — change the destination's URL or selected events.
- Disable — stop sending events to this destination.
- Delete — remove the destination permanently.
Events to select
In the Events section, the Selected events tab shows the events already chosen, and All events lets you search and add others. The payment integration uses the following events:
| Category | Event | Sent by Stripe when… |
|---|---|---|
| Checkout | checkout.session.completed |
A Checkout Session has been successfully completed. |
| Customer | customer.subscription.created |
A customer signs up for a new plan. |
| Customer | customer.subscription.deleted |
A customer's subscription ends. |
| Customer | customer.subscription.updated |
A subscription changes, for example a plan switch or a status change from trial to active. |
| Invoice | invoice.paid |
An invoice payment succeeds, or an invoice is marked as paid outside Stripe. |
Result: The destination appears as Active in the list with 5 events under Listening to.
III. Copy the signing secret
Go to: Workbench > Webhooks > click the destination URL to open its details page.
- On the destination's Overview tab, locate the Signing secret field. The value is masked and starts with
whsec_. - Click the eye icon to reveal the full value.
- Copy the complete value, including the
whsec_prefix.
Result: You have the value to paste into the platform's Stripe webhook signature field (Section V).
IV. Copy the Stripe secret key
Go to: Stripe Dashboard > Developers > API keys.
- Open Developers at the bottom of the left-hand menu and select API keys.
- In the Standard keys section, locate the Secret key row.
- Reveal and copy the secret key.
Result: You have the value to paste into the platform's Stripe account API key field (Section V).
V. Enter the values in the platform
Go to: the platform's Payment integration settings.
- Paste each value copied from Stripe into its matching field, following the table below.
- Check that test values are in the Test fields and live values in the Live fields.
- Save your changes.
| Platform field | Value to paste from Stripe |
|---|---|
| Test Stripe account API key | Secret key, test mode (Section IV) |
| Live Stripe account API key | Secret key, live mode (Section IV) |
| Test Stripe webhook signature | Signing secret of the test-mode destination (Section III) |
| Live Stripe webhook signature | Signing secret of the live-mode destination (Section III) |
Result: The platform can communicate with your Stripe account and verify the authenticity of webhook requests in each mode. Saved values remain masked in the fields.
VI. Check event deliveries
Go to: Workbench > Webhooks > destination details > Event deliveries tab.
- Open the Event deliveries tab to see every event Stripe sent to the destination, grouped by date.
- Use Find event by ID or the Status filter to locate a specific delivery. Click Refresh to load the latest attempts.
- Select an event to see its Delivery attempt details, including the Delivery status.
- If a delivery failed and the cause has been fixed, click Resend to send it again.
Result: A 200 OK status with a Delivered delivery status confirms the platform received and accepted the event.
FAQ & Troubleshooting
Troubleshooting failed deliveries
| Issue | Likely cause | Resolution |
|---|---|---|
| Deliveries fail right after setup or after rolling the secret | The Stripe webhook signature in the platform does not match the destination's current signing secret | Copy the signing secret again (Section III), paste it in the matching field (Section V), then Resend the failed events |
| Test events fail but live events succeed (or the reverse) | Test and live values were swapped, or entered in the wrong fields | Check each value against the mapping table in Section V |
| No deliveries appear at all | The destination is disabled, points to the wrong URL, or does not listen to the required events | Check the destination's status, URL, and selected events (Section II) |
| The destination's Error rate increases | The endpoint rejects or does not answer some events | Open Event deliveries, filter by Status, and review the failed attempts. Contact Support with the event IDs if the cause is unclear |
-
Issue: Payments succeed in Stripe but nothing is updated on the platform.
Solution: The platform did not receive or accept the event. Check that the destination is Active, listens to the five required events (Section II), and that its deliveries show 200 OK (Section VI). If deliveries fail, update the Stripe webhook signature and resend the events.
Issue: The platform cannot communicate with Stripe after the API key was entered.
Solution: The Publishable key may have been pasted instead of the Secret key, or a test key entered in a live field. Copy the Secret key from Developers > API keys in the correct mode and paste it again.
Issue: Webhooks stopped working after someone changed settings in Stripe.
Solution: The signing secret was rolled, the destination was disabled or edited, or the secret key was changed. Compare the current Stripe values with those in the platform's Payment integration fields and update any that differ.
Issue: I cannot find the Webhooks or API keys pages in Stripe.
Solution: Your Stripe role may not give access to the Developers area, or another Stripe account is selected. Check the account name at the top of the left-hand menu, or ask your Stripe account owner for access.
-
Do I need to fill in both the test and live fields?
— Fill in the fields for each mode you use. Test values let you validate the setup without real payments; live values are required to process real payments.
Is the Publishable key used anywhere in this setup?
— No. The Payment integration fields expect the Secret key and the webhook Signing secret only.
Can I view the signing secret again later?
— Yes. Stripe lets you view or roll the signing secret at any time from the destination details page.
What happens if I disable or delete the destination in Stripe?
— Stripe stops sending events to the platform, so payment updates are no longer received. Re-enable the destination or create a new one, then update the Stripe webhook signature if the signing secret changed.
Why are the values masked in the platform after saving?
— The keys and signatures are sensitive. The fields remain masked to prevent them from being exposed on screen. -
Contact Support
Technical documentation
API documentation
Stripe documentation: webhooks
Stripe documentation: API keys
Service status page