Setting up the Stripe webhook

Overview

A webhook is Stripe's way of reporting back to Kyvento: whenever something happens in Stripe that Kyvento needs to know about – a payment is finalized, an amount is refunded, a customer opens a dispute (chargeback) or a SEPA direct debit fails –, Stripe sends a message to a fixed address in Kyvento. Without this return channel, Kyvento only sees the immediate payment, but none of these follow-up events. The result: invoices stay marked as "paid" even though the money has long since flowed back. This article walks through setting up the webhook step by step – it is a two-way setup: you enter the Kyvento webhook URL in Stripe and then transfer the signing secret generated by Stripe back into Kyvento.

Before you start

• Your own Stripe account with access to the Stripe dashboard (dashboard.stripe.com).
• Your API keys from the Stripe dashboard for the "Manual API Keys" route (Settings → Payments → Stripe). Kyvento only saves them together with the signing secret from step 4 – so you enter the keys and the secret together at the end.
• In Kyvento, permission to manage settings (e.g. the "Administrator" or "Full access" system role).
• Mind the mode: test and live mode have separate webhooks and separate signing secrets in Stripe. Set up the webhook in the same mode you run Stripe in within Kyvento.

Step 1: Copy the webhook URL from Kyvento

1. In Kyvento, open Settings → Payments → Stripe.
2. Find the "Webhook URL" card. It shows your personal, account-bound address – it ends with your Kyvento account number and looks something like: https://app.kyvento.com/api/webhooks/stripe/123.
3. Click the copy icon to put the full URL on your clipboard.

Step 2: Create the webhook endpoint in Stripe

1. Sign in to the Stripe dashboard and select the correct mode (Test or Live) at the top right.
2. Open Developers → Webhooks and click "Add endpoint".
3. Paste the Kyvento URL you copied in step 1 into "Endpoint URL".
4. Optionally add a description, e.g. "Kyvento".

Step 3: Select the correct events

Click "Select events" and choose exactly these event types. Kyvento processes only the following – a missing event means the corresponding action never reaches Kyvento:

• payment_intent.succeeded – payment completed successfully (invoice set to "paid")
• payment_intent.processing – payment in progress (e.g. a SEPA first payment not yet final)
• payment_intent.payment_failed – payment failed
• payment_intent.requires_action – additional confirmation required (3-D Secure/SCA)
• charge.refunded – amount refunded (also for a failed SEPA direct debit)
• charge.dispute.created – customer opens a dispute (chargeback)
• charge.dispute.closed – dispute closed (won/lost)
• payment_method.updated – updated card details (automatic card renewal)
• setup_intent.succeeded – payment method stored successfully
• setup_intent.setup_failed – storing the payment method failed

You do not need to enable any further events. Additional types do no harm, but they create unnecessary deliveries that Kyvento ignores.

5. Confirm the selection and click "Add endpoint" to save the webhook.

Step 4: Transfer the signing secret back to Kyvento

So that Kyvento can be sure a message really comes from your Stripe account, it verifies every delivery with a secret key – the signing secret. Without this secret, Kyvento rejects all events and does not accept any payments via Stripe – so this step is mandatory, not optional.

1. In Stripe, open the endpoint you just created.
2. In the "Signing secret" section, click "Reveal" and copy the value. It starts with whsec_.
3. Switch back to Kyvento: Settings → Payments → Stripe.
4. Open the "Manual API Keys" section (the "Configure manually" button).
5. Enter your API keys there if you have not done so yet, and paste the copied value into the "Webhook Secret" field.
6. Save the settings.

Verifying success

Finally, check that the connection actually works:

1. In Stripe, open the endpoint and click "Send test webhook".
2. Select the payment_intent.succeeded event and send it.
3. In the endpoint's event log, the delivery must appear with status HTTP 200.

As a real cross-check: trigger a test payment – it appears in Kyvento as "paid". Then refund that payment in the Stripe dashboard; in Kyvento the corresponding payment then shows as "Refunded" (in the invoice's payment overview).

If it doesn't work

• Status 400 in the Stripe log: The signing secret in Kyvento doesn't match the endpoint. Check that you copied the value from the correct mode (test/live) and pasted it in full.
• Status 403: No signing secret is stored in Kyvento yet – step 4 has not been completed. With your own API keys, Kyvento does not accept any payments via Stripe until then either. Paste the whsec_… value into the "Webhook Secret" field and save.
• Status 404: The endpoint URL is incomplete – usually the account number at the end is missing. Copy the URL again from the "Webhook URL" card.
• Refunds/disputes don't arrive, but payments do: The charge.* types are missing from the event selection. Add them to the Stripe endpoint.

Next steps

• Set up the PayPal webhook – see Setting up the PayPal webhook
• Connect credit card payments with Stripe – see Accepting credit card payments
• Trace refunds and chargebacks in your accounting – see Credit notes and cancellations