Skip to main content
Webhooks allow CeyPay to notify your WooCommerce store in real-time when payment events occur. This ensures orders are updated immediately when customers complete their payments.

​
Webhook Endpoint

CeyPay sends webhook notifications to your store’s WooCommerce API endpoint: 
https://yoursite.com/?wc-api=WC_Gateway_CeyPay
The webhook URL is generated automatically by WooCommerce. You can find the exact URL by checking the webhook configuration in your CeyPay dashboard or by examining the webhookUrl parameter in API requests.

​
Webhook Events

CeyPay sends webhooks for the following payment status changes:
StatusDescriptionWooCommerce Action
SUCCESSPayment completed successfullyOrder marked as “Processing”
PAIDPayment confirmed (alias for SUCCESS)Order marked as “Processing”
EXPIREDPayment window expiredOrder marked as “Failed”
FAILEDPayment was declined or erroredOrder marked as “Failed”

​
Webhook Payload

​
Request Headers

Each webhook request includes these headers for verification:
HeaderDescription
X-Webhook-SignatureHMAC-SHA256 signature of the payload
X-Webhook-TimestampUnix timestamp when the webhook was sent
Content-TypeAlways application/json

​
Request Body

The webhook payload is a JSON object containing payment details:
​
paymentId
string
required
Unique identifier for the payment transaction. This is stored in the order metadata as _ceypay_transaction_id.
​
transactionId
string
Alternative field name for the payment ID. The plugin accepts either paymentId or transactionId.
​
status
string
required
Current payment status. One of: SUCCESS, PAID, EXPIRED, FAILED.

​
Example Payload

{
  "paymentId": "pay_abc123xyz789",
  "status": "SUCCESS",
  "amount": 100.0,
  "currency": "USD",
  "provider": "BINANCE"
}

​
Signature Verification

All webhook requests are signed using HMAC-SHA256 to ensure authenticity. The plugin automatically verifies signatures before processing any webhook.

​
How Signatures Work

  1. CeyPay concatenates the timestamp and JSON payload
  2. The combined string is hashed using HMAC-SHA256 with your webhook secret
  3. The resulting signature is included in the X-Webhook-Signature header

​
Verification Process

The plugin verifies signatures using this logic: 
// Construct signature payload
$signature_payload = $timestamp . $json_body;

// Compute expected signature
$expected_signature = hash_hmac('sha256', $signature_payload, $webhook_secret);

// Compare signatures (timing-safe)
if (hash_equals($expected_signature, $received_signature)) {
    // Signature valid - process webhook
} else {
    // Signature invalid - reject request
}
If signature verification fails, the webhook returns a 401 Unauthorized response and the request is logged. Check your webhook secret configuration if you see signature mismatch errors.

​
Test Mode Signatures

When Test Mode is enabled, the plugin uses a predefined secret (mock_secret_key) for signature verification. This allows the test server to send valid webhooks without configuring your production credentials.

​
Order Matching

The plugin matches incoming webhooks to WooCommerce orders using the transaction ID stored in order metadata.

​
Lookup Process

  1. Extract paymentId or transactionId from webhook payload
  2. Query WooCommerce orders for meta key _ceypay_transaction_id
  3. If found, update the order status based on payment status
  4. If not found, log the error (order may have been deleted)

​
Stored Order Metadata

The following metadata is stored on each order:
Meta KeyDescription
_ceypay_transaction_idCeyPay transaction identifier
_ceypay_providerSelected payment provider (BYBIT, BINANCE, KUCOIN)
_ceypay_qr_code_urlQR code content URL
_ceypay_deep_linkDeep link URL for mobile wallets
Available Providers:

Bybit

Binance Pay

KuCoin

​
Handling Webhook Responses

​
Success Response

Return HTTP 200 OK to acknowledge successful webhook processing: 
HTTP/1.1 200 OK

​
Error Responses

Status CodeMeaning
400 Bad RequestInvalid or malformed payload
401 UnauthorizedSignature verification failed
405 Method Not AllowedNon-POST request received
500 Internal Server ErrorWebhook secret not configured

​
Debugging Webhooks

​
Enable Logging

In Test Mode, webhook activity is automatically logged to WooCommerce logs. Access logs at: WooCommerce > Status > Logs → Select files prefixed with ceypay-

​
Log Entries

Typical log entries include: 
Webhook received: {"paymentId":"pay_123","status":"SUCCESS"}
Signature Check: Received: abc... Computed: abc... Match: YES
Processing webhook for Transaction ID: pay_123, Status: SUCCESS
Order #456 marked as paid.

​
Common Issues

Cause: Webhook secret doesn’t match between CeyPay dashboard and plugin settings.Solution: Copy the webhook secret directly from your CeyPay dashboard and paste it into the plugin settings. Avoid adding extra spaces or characters.
Cause: The order was deleted, or the customer abandoned checkout before the QR code was generated.Solution: This is usually expected behavior for abandoned checkouts. No action required.
Cause: Server firewall blocking incoming requests, or site not accessible from internet.Solution: Ensure your site has a valid SSL certificate and is publicly accessible. Check server firewall rules.

​
Security Best Practices

Keep Secret Secure

Never expose your webhook secret in client-side code, version control, or public logs.

Use HTTPS

Always use HTTPS for your webhook endpoint. HTTP webhooks should be rejected.

Verify Signatures

Always verify webhook signatures. The plugin does this automatically.

Idempotency

Handle duplicate webhooks gracefully. The plugin checks order status before updating.

​
Retry Policy

If your webhook endpoint is unavailable, CeyPay may retry the webhook. The plugin handles this by checking if the order is already processed before making changes.
The plugin includes fallback payment status polling, so even if a webhook fails, payments will still be confirmed when the customer’s browser polls for status updates.

​
Next Steps

Troubleshooting

Solutions for common webhook and integration issues.

Configuration

Review all available plugin settings.