Skip to main content

​
Webhooks

​
Intro

Khaime notifies your store automatically when a payment succeeds or fails, and when a subscription’s status changes — this is what marks orders as paid without any manual step.

​
Context

Webhooks are the other half of the payment flow: the plugin creates the charge, and Khaime’s webhook is what confirms it back to WooCommerce. Setup depends on configuration being complete first (API key and webhook secret saved). For the endpoint, event list, and signature details, see the Developer Reference.

​
Hows

​
Setup

During configuration you copy your store’s webhook URL into Khaime:
  1. In WooCommerce → Khaime, copy the webhook URL.
  2. Paste it into Khaime Dashboard → Settings → API → Webhook URL.
That’s the only setup required. See Configuration.

​
What updates automatically

  • A successful payment marks the order paid and records the transaction.
  • A failed payment marks the order failed with the failure reason as an order note.
  • Subscription creation, renewal, and cancellation update the corresponding WooCommerce Subscription automatically.
Refunds are the exception: they’re confirmed synchronously when you issue them from WooCommerce → Orders, not via webhook — see Payment Flow → Refunds.

​
Troubleshooting

Orders aren’t being marked paid
  • Confirm the webhook URL in your Khaime Dashboard matches the one in WooCommerce → Khaime.
  • Make sure your store is reachable from the internet (webhooks can’t reach a localhost or password-protected site).
  • Check Khaime Dashboard → Webhooks for delivery status and errors.
A security or caching plugin may interfere
  • If deliveries fail verification, check whether a WAF or caching plugin is altering incoming requests before they reach WordPress.
Building an integration or debugging delivery details (events, signatures, endpoint)? See the Developer Reference.

​
Whys

Payment confirmation is pushed via webhook rather than polled, because the definitive signal that money moved comes from the gateway to Khaime, not from the customer’s browser — a customer can close the tab, lose connectivity, or have their return-redirect blocked, and the order still needs to end up in the correct state. Refunds don’t need the same mechanism: a refund is something you initiate from WooCommerce, so the plugin can just call Khaime synchronously and read the response directly, with no round trip needed.

​
Why nots

  • Not a general-purpose event stream. The plugin only acts on the payment and subscription lifecycle events relevant to keeping a WooCommerce order in sync — it doesn’t surface every event type Khaime’s platform emits (disputes, settlements, wallet activity, and so on have no WooCommerce-side effect).
  • Won’t fire against an unreachable store. If your store isn’t publicly reachable — local development, a password-protected staging site — webhooks can’t be delivered. Use the Developer Reference’s diagnostics panel for local testing instead.
  • Not the mechanism for refund confirmation. Don’t expect a refund to show up because a webhook arrived — it’s already been recorded synchronously by the time you see the order note.