Connecting Stripe Webhooks

Add a Stripe webhook to a payment gateway so late payments complete, Stripe refunds are recorded and disputes reach you.

A Stripe webhook lets Stripe tell your workspace about payment events after they happen. Each Stripe gateway has its own webhook, set up on Billing > Payment Gateways (/brand/gateways) in the Stripe webhook card for that gateway.

Checkout works without a webhook. With one connected:

  • A payment that finishes after the customer has left the page (PayPal and other redirect or delayed payment methods) still completes the customer's order.

  • A refund you make in the Stripe Dashboard is recorded on the customer's transaction.

  • A dispute (chargeback) is recorded, and the workspace owner gets an email when it opens and again when it closes.

Viewing the card needs brand.gateways.view. Saving or removing the signing secret needs brand.gateways.manage.

Set up the webhook

  1. Go to Billing > Payment Gateways and find the Stripe webhook card for the gateway. Its title includes the gateway's name.

  2. Click Copy next to Endpoint URL.

  3. In the Stripe Dashboard, make sure you are in the same mode as the keys on this gateway: test mode for test keys, live mode for live keys.

  4. Open Webhooks (under Developers) and add an endpoint. Stripe may call it an event destination. Choose events from your own account.

  5. Paste the endpoint URL.

  6. Select these events (the card lists the same ones):

    • payment_intent.succeeded

    • payment_intent.payment_failed

    • charge.refunded

    • charge.refund.updated

    • charge.dispute.created

    • charge.dispute.updated

    • charge.dispute.closed

  7. When Stripe asks for an API version, keep the version it shows. Any version works.

  8. Create the endpoint, then reveal its Signing secret in Stripe. It starts with whsec_.

  9. Back on the card, paste it into Signing secret and click Save.

The card now shows the signing secret as Saved. The secret is never shown again on this page, so keep your copy in Stripe.

If you have more than one Stripe gateway, repeat these steps for each one. Every gateway has its own endpoint URL and its own signing secret.

Replace or remove the secret

  • Replace secret: paste a new signing secret, for example after you roll the secret in Stripe or recreate the endpoint. Save it as soon as Stripe gives it to you, because Stripe signs new events with the new secret.

  • Remove secret: your workspace refuses this gateway's webhook events until you save a new secret. Checkout keeps working.

What you see

  • Late payments: the customer's order completes as if they had stayed on the page. If they come back to the page later, they see their order confirmed and continue as usual. The same goes for SharePay top-ups: the credit arrives even if the payer closed the page before it finished.

  • Refunds made in Stripe: the refund appears on the transaction under Users > Transactions, like a refund made in the panel. A refund that Stripe takes a while to complete appears once Stripe reports it as succeeded. It does not change the customer's account credit or any referral commission. If the refund should also do either, adjust them yourself. A refund made in the panel is never recorded twice.

  • Disputes: the workspace owner gets an email with the payment, the customer, the disputed amount, the reason and the date to respond by. Respond to the dispute in the Stripe Dashboard. Nothing is refunded or changed in your workspace; you decide what to do with the customer's order and services. A second email follows when the dispute closes, with the outcome.

Troubleshooting

Stripe shows each delivery and the answer it got on the endpoint's page in the Stripe Dashboard.

  • 404 "Webhook endpoint not found": no signing secret is saved for the gateway in the URL. Check that the endpoint URL in Stripe matches the one on the card, then save the secret.

  • 400 "Webhook signature could not be verified": the saved secret is not this endpoint's secret. Copy the signing secret from the endpoint in Stripe and save it again with Replace secret.

  • Events arrive but nothing changes: check that the endpoint and the gateway's keys are in the same mode (test or live). Events about payments that were not made through this gateway are ignored.