Documentation Index
Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
Use this file to discover all available pages before exploring further.
WooCommerce Webhooks
The plugin registers a REST API endpoint to receive webhooks from Khaime:Setup
- Copy the webhook URL from WooCommerce → Settings → KhaimePay
- Add it to your Khaime Dashboard → Settings → API → Webhook URL
Security
Every webhook is verified before processing:- Signature verification: HMAC-SHA256 using your webhook secret (from the
X-Khaime-Signatureheader) - Event deduplication: Each event has a unique ID (
X-Khaime-Event-Id) that is checked against a 48-hour replay window to prevent duplicate processing - Payload validation: Required fields are checked before processing
Handled Events
| Event | Action |
|---|---|
payment.succeeded | Marks order as paid, stores transaction ID, payment amount, and currency |
payment.failed | Marks order as failed, adds order note with failure reason |
subscription.created | Stores subscription ID, frequency, and next payment date on the order |
subscription.renewed | Processes the subscription renewal |
subscription.cancelled | Cancels the WooCommerce subscription |
refund.completed | Adds an order note confirming the refund with amount and currency |
Payment Succeeded Details
When apayment.succeeded webhook is received, the plugin stores:
- Transaction ID
- Payment session ID
- Payment gateway used
- Amount the customer actually paid
- Currency the customer paid in
- Subscription details (if applicable)
Logging
Webhook events are logged to WooCommerce → Status → Logs under thekhaime-webhooks source.
Troubleshooting
Webhooks not arriving
- Verify the webhook URL is correct in Khaime Dashboard
- Check that your site is accessible from the internet (not localhost)
- Check server firewall rules — the endpoint must accept POST requests
- Review Khaime Dashboard → Webhooks for delivery status and error details
Signature verification failing
- Ensure the webhook secret matches between WooCommerce settings and Khaime Dashboard
- Check that no middleware, WAF, or caching plugin is modifying the request body before it reaches WordPress
Duplicate order completion
- The plugin automatically deduplicates webhook events within a 48-hour window. If you see duplicates, check that the event IDs are actually different in the Khaime Dashboard.