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
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.