Support

Help and documentation

API & webhooks

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 you 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.

Does this apply to me? This guide only applies if you connected Stripe in Kyvento via "Manual API Keys" (your own Stripe account with your own API keys). If you instead use "Connect with Stripe" (Stripe Connect), Kyvento receives all Stripe events automatically through the platform – you then do not need to create a webhook or enter a signing secret. In that case the webhook URL shown is for information only.

Before you start

  • Your own Stripe account with access to the Stripe dashboard (dashboard.stripe.com).
  • Stripe is set up in Kyvento via "Manual API Keys" (Settings → Payments → Stripe).
  • 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.

Important: Always copy the URL in full, including the number at the end. That number assigns the events to your account – without it the webhook goes nowhere.

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.

  1. 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.

  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. 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. 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"