How to set up the payment webhook (so orders are marked paid)

A TeleportHQ store learns that a shopper has paid through a webhook: a message your payment provider sends to your published site after each payment. For Stripe and PayPal, publishing your store to Production sets it up for you. For Square and Paddle, publish, click Connect automatically in the provider's Webhook section, then publish again. Razorpay needs the webhook added by hand, and Mollie and CoinGate need nothing. Without a working webhook, paid orders stay pending.

Before you start#

• Connect the provider and save its keys first. See How to accept payments with Stripe or PayPal.
• The webhook needs your store's public address, so it's set up after you publish to Production. See How to publish your site.
• Providers can't reach a site that asks for a password. If you password-protected your site, remove the password before you take payments. On the TeleportHQ trial, every publish puts your site behind a password, so payment messages reach your store once the workspace subscribes and you remove the password. See How to password-protect your site.

What each TeleportHQ payment provider needs#

Before you publish: the Webhook section#

Open the provider: in the editor's left icon column, click E-commerce, then click the provider's card under Payment Providers. The Configure panel has a Webhook section with a status:

• After you publish: the store has no public address yet. For Stripe and PayPal it says "Publishing your store connects it for you."
• Not set up: the store is live, but the webhook isn't connected yet.
• Connected: the webhook's secret is saved.
• Automatic: Mollie and CoinGate, nothing to do.

Stripe and PayPal: publish#

1. At the top right, click Publish.
2. Keep Production selected and click Publish to Production.
3. When the publish ends, a message says "Stripe's webhook is connected: orders paid with Stripe are confirmed automatically." (or the same for PayPal).

The provider's card in Payment Providers now says Connected. The saved secret reaches your live site with your next publish; until then, your store checks each payment with Stripe or PayPal directly.

Square, Paddle, or a webhook that didn't connect: Connect automatically#

Use this for Square and Paddle, or for Stripe and PayPal when the message after publishing says "Stripe's webhook could not be connected automatically".

1. In the E-Commerce panel, click the provider's card. You can also click Set up on the orange banner "… needs its webhook", or Connect Stripe in the Publish window's Connect your payment webhooks box.
2. In the Webhook section, check the Webhook URL. It's your live address followed by /api/webhooks/stripe-payment (or paypal-payment, square-payment and so on).
3. Click Connect automatically. TeleportHQ creates the webhook in your provider account with every event the store needs, and saves its secret. The section says "Connected: Square now sends every payment event to your store." If the button is greyed out with "Save your Access token above first.", save the provider's keys first.
4. For Square and Paddle, publish again: your live store checks their messages with the saved key from its next build.

Set it up yourself in the provider's dashboard#

Every provider except Mollie and CoinGate has a step-by-step guide in its Webhook section, with links to the right screens and the exact list of events to tick. Click How do I set up the Stripe webhook? (on a published store, Stripe, PayPal, Square and Paddle call it Or set it up yourself in Stripe, or in your provider). Before you publish, the guide shows a placeholder address; after publishing, it shows your real webhook URL.

Stripe, in short:

1. Open Workbench → Webhooks in the same mode as your secret key (a test key or a live key).
2. Click Create an event destination (Add endpoint in older dashboards) and choose Your account.
3. Select the events the guide lists, such as checkout.session.completed and charge.refunded, then click Continue. Click the copy button above the list to copy every event name. Subscription events are needed only if you sell subscriptions.
4. Choose Webhook endpoint, click Continue, and paste the Webhook URL in Endpoint URL.
5. Click Create destination. Reveal the Signing secret (it starts with whsec_) and paste it into the Signing secret field below the guide in TeleportHQ.
6. Click Save Configuration, then publish again.

PayPal: in Apps & Credentials, open your app, click Add Webhook, paste the Webhook URL, tick the events under Event types, click Save, then copy the new webhook's Webhook ID into the Webhook ID field in TeleportHQ.

Razorpay: in Accounts & Settings → Webhooks, click + Add New Webhook, paste the URL, type a secret of your own in Secret, and type the same value in the Webhook Secret field in TeleportHQ. Razorpay calls the secret optional, but the store refuses every Razorpay webhook without it.

Check my webhook#

On a published store, the Stripe, PayPal, Square and Paddle guides end with Verify: open Or set it up yourself in Stripe (or your provider) and click Check my webhook. TeleportHQ reads the endpoints in your provider account, says which events each one is missing, and lets you add the missing ones from the editor.

Check that it worked#

The provider's card says Connected, and its Webhook section shows the same status. Place a test order on your published site and pay. See How to test payments before going live. In Growth → E-Commerce → Orders, the order's status changes from Pending to Confirmed, and its payment status is Paid. If Invoices is on in the store settings, the order also gets a PDF invoice.

Troubleshooting#

Orders stay pending after the shopper paid, and the card says "Webhook needed" Your store is live, but the webhook isn't connected. Point at Webhook needed for the explanation, then click the card and follow the steps above.

"Your site asks visitors for a password, and so it asks Stripe too: no webhook can reach it. Make the site public before you take payments: remove the password in the Publish window, which on a trial takes a subscription." A password on your site also blocks payment messages. On Pro or Premium, click Remove under Password Protection in the Publish window before you take payments. On the trial, the password can't be removed: subscribe the workspace first, then remove it.

"Your Stripe endpoint for this store now receives every event the store needs, but Stripe shows its Signing secret only once. Reveal it in Stripe and paste it below." Your Stripe account already had an endpoint for this store, so TeleportHQ completed it but couldn't read its secret. Reveal the Signing secret in Stripe and paste it into Signing secret, then click Save Configuration.

"Until the Signature key is saved, the store refuses every Square webhook: no order can be marked paid." Square, Paddle and Razorpay check every message with a key. Click Connect automatically, or paste the key from your provider dashboard, then publish again.

Payments stopped being confirmed after you changed your domain The webhook URL includes your site's address and uses your custom domain once you have one. Open the provider and click Connect automatically (or check it with Check my webhook), then publish. For Razorpay, update the URL in its dashboard. See How to connect your own domain.

PayPal test events are refused PayPal's Webhooks Simulator sends events PayPal itself can't verify, so the store refuses them. Test with a real sandbox purchase.

Good to know#

• What the webhook does. When a payment is confirmed, your site marks the order paid, adds the payment to the order's history and creates the invoice if Invoices is on. It also records refunds made in your provider's dashboard and keeps subscriptions up to date.
• Test and live are separate. When you switch from test keys to live keys, click Connect automatically again (or create a live-mode webhook by hand), so the live account gets its own webhook and secret. See How to test payments before going live.
• Webhook URL address. The URL uses your custom domain when you have one, otherwise your TeleportHQ address. The automatic connection after publishing waits until a custom domain is verified.
• Only a TeleportHQ publish connects it. The automatic connection runs after a publish to Production on TeleportHQ hosting. If you publish with your own Vercel account, use Connect automatically instead.