Configuring Stripe Webhooks

This guide is for tenants running their own Stripe account, which means the Payment Mode on Settings → Business Settings → Commerce → Payments & Checkout is set to Tenant Owned or Hybrid. If your payment mode is Babylon Managed (Babylon's managed Stripe account, operated by Babylon) or Offline Only, you don't need this guide: Babylon already receives payment events for you, and the Stripe fields described below are hidden.

Webhooks are how Stripe tells Babylon that a payment succeeded, a card was declined, a subscription renewed or an identity check finished. Without them, orders and verifications in your admin console can fall out of step with what actually happened in Stripe.

Before you start

You'll need:

• Access to your Stripe Dashboard with permission to create webhook endpoints.
• Permission to manage business settings in Babylon, so you can open Settings → Business Settings.
• Your Babylon tenant ID. It is shown at the top of Settings → Communications, next to "tenant id". It is a 26 character code such as 01hxxxxxxxxxxxxxxxxxxxxxxx; copy it exactly as shown. If you can't open that page, ask Hammerd support for it.
• A few minutes per environment. You'll repeat these steps once for Test and once for Live, because Stripe keeps test and live webhook endpoints separate.

Everything you paste into Babylon lives in Settings → Business Settings → Commerce → Stripe & Payouts, in the Stripe (Test) or Stripe (Live) group. Secret fields never show a stored value again: once saved they read "Configured" with the last four characters. Leave a secret field blank to keep what is already stored.

In the URLs below, replace {your-platform-host} with the shared platform address for your account. Check Platform Backend Base on Settings → Business Settings → Advanced → Platform Backend Routing: if it is hammerd.io, use app.hammerd.io; if it is babylon.host, use app.babylon.host. Replace {your-tenant-id} with your tenant ID and {environment} with test or live, matching the Stripe mode you're configuring.

1. Payment webhooks

Payment webhooks keep orders and invoices in step when a buyer's card is charged, declined, refunded or disputed.

Endpoint URL:

https://{your-platform-host}/api/webhooks/stripe/{your-tenant-id}/{environment}/payments

Steps:

1. In the Stripe Dashboard, go to Developers → Webhooks and add an endpoint.
2. Enter the endpoint URL above.
3. Select these events: payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created.
4. Save the endpoint, then copy its Signing secret (it starts with whsec_).
5. In Babylon, paste it into Webhook Secret (Test) or Webhook Secret (Live) and save the page.

2. Billing webhooks (subscriptions and invoices)

If you use Stripe for recurring billing, set up a second endpoint so subscription and invoice changes reach Babylon too.

Endpoint URL:

https://{your-platform-host}/api/webhooks/stripe/{your-tenant-id}/{environment}/billing

Steps:

1. In the Stripe Dashboard, add another endpoint using the billing URL above.
2. Select these events: customer.subscription.updated, customer.subscription.deleted, customer.subscription.trial_will_end, invoice.payment_succeeded, invoice.payment_failed.
3. Save the endpoint and copy its Signing secret.
4. In Babylon, paste it into Billing Webhook Secret (Test) or Billing Webhook Secret (Live) and save.

Optional field. If you leave the billing webhook secret empty, billing events are checked against the payments Webhook Secret for the same environment instead. That only works if you used the same Stripe endpoint secret for both, so in practice set a separate billing secret whenever you created a separate billing endpoint.

3. Identity (KYC) webhooks

If you verify sellers or bidders with Stripe Identity on your own Stripe account, Stripe sends the result of each verification as a webhook. Until this is configured, Stripe Identity results for your account are rejected and verifications stay stuck in progress.

Endpoint URL (note that this one has no /api in the path):

https://{your-platform-host}/webhooks/stripe/identity/{your-tenant-id}/{environment}

Steps:

1. In the Stripe Dashboard, add another endpoint using the identity URL above.
2. Select these events: identity.verification_session.processing, identity.verification_session.verified, identity.verification_session.requires_input.
3. Save the endpoint and copy its Signing secret.
4. In Babylon, paste it into Identity (KYC) Webhook Secret (Test) or Identity (KYC) Webhook Secret (Live) and save.

Other identity.verification_session events can be selected without harm, but Babylon ignores them. See Identity verification for how verification works in the admin console.

Testing your setup

Use the Stripe CLI against your test account to create a sample event, for example:

stripe trigger payment_intent.succeeded

Then open the endpoint in the Stripe Dashboard and check that the delivery shows a 200 response. A 400 response almost always means the signing secret in Babylon doesn't match the endpoint, or hasn't been saved for that environment.

Going live

The Active Stripe Environment setting on the same page decides which set of keys checkout uses. When you switch it between Test and Live, Babylon asks you to confirm before saving, because switching to live starts charging real cards and switching back to test stops real payments working. Set up and test all three live endpoints before you switch. See Payments and checkout for the full picture.

Troubleshooting

Deliveries fail in the Stripe Dashboard

• Check the endpoint URL. Payment and billing URLs include /api/; the identity URL does not.
• Check that the tenant ID and environment in the URL match where you pasted the secret. A live endpoint needs the secret in the Stripe (Live) group.
• If you ever roll the signing secret in Stripe, paste the new one into Babylon as well.

Payments succeed in Stripe but orders don't update in Babylon

• This is almost always a missing or mismatched Webhook Secret. Recheck step 5 of the payments section.
• Confirm your Payment Mode is still Tenant Owned or Hybrid. Webhooks for your own Stripe account are only used in those modes.

Identity verifications stay in progress after Stripe shows them complete

• The Identity (KYC) Webhook Secret for that environment is missing or wrong. Set it and ask the person to retry if their session has expired.

Still stuck? Contact Hammerd support with the endpoint URL and the event type that isn't arriving, and we can check delivery on our side. Never send us your secret keys or signing secrets.