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

# Webhooks

> How the WooCommerce plugin handles Khaime webhooks.

# WooCommerce Webhooks

The plugin registers a REST API endpoint to receive webhooks from Khaime:

```
POST https://yourstore.com/wp-json/khaime/v1/webhook
```

## Setup

1. Copy the webhook URL from **WooCommerce → Settings → KhaimePay**
2. Add it to your **Khaime Dashboard → Settings → API → Webhook URL**

## Security

Every webhook is verified before processing:

1. **Signature verification**: HMAC-SHA256 using your webhook secret (from the `X-Khaime-Signature` header)
2. **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
3. **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 a `payment.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 the `khaime-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.