Webhooks

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:

Status	Description	WooCommerce Action
`SUCCESS`	Payment completed successfully	Order marked as “Processing”
`PAID`	Payment confirmed (alias for SUCCESS)	Order marked as “Processing”
`EXPIRED`	Payment window expired	Order marked as “Failed”
`FAILED`	Payment was declined or errored	Order marked as “Failed”

Webhook Payload

Request Headers

Each webhook request includes these headers for verification:

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature of the payload
`X-Webhook-Timestamp`	Unix timestamp when the webhook was sent
`Content-Type`	Always `application/json`

Request Body

The webhook payload is a JSON object containing payment details:

string

required

Unique identifier for the payment transaction. This is stored in the order metadata as _ceypay_transaction_id.

string

Alternative field name for the payment ID. The plugin accepts either paymentId or transactionId.

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

CeyPay concatenates the timestamp and JSON payload
The combined string is hashed using HMAC-SHA256 with your webhook secret
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

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

Stored Order Metadata

The following metadata is stored on each order:

Meta Key	Description
`_ceypay_transaction_id`	CeyPay transaction identifier
`_ceypay_provider`	Selected payment provider (BYBIT, BINANCE, KUCOIN)
`_ceypay_qr_code_url`	QR code content URL
`_ceypay_deep_link`	Deep link URL for mobile wallets

Available Providers:

Handling Webhook Responses

Success Response

Return HTTP 200 OK to acknowledge successful webhook processing:

HTTP/1.1 200 OK

Error Responses

Status Code	Meaning
`400 Bad Request`	Invalid or malformed payload
`401 Unauthorized`	Signature verification failed
`405 Method Not Allowed`	Non-POST request received
`500 Internal Server Error`	Webhook 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

Signature Mismatch

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.

Order Not Found

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.

Webhooks Not Received

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.

Getting Started

Integrations

Resources

Webhook Endpoint

Webhook Events

Webhook Payload

Request Headers

Request Body

Example Payload

Signature Verification

How Signatures Work

Verification Process

Test Mode Signatures

Order Matching

Lookup Process

Stored Order Metadata

Handling Webhook Responses

Success Response

Error Responses

Debugging Webhooks

Enable Logging

Log Entries

Common Issues

Security Best Practices

Keep Secret Secure

Use HTTPS

Verify Signatures

Idempotency

Retry Policy

Next Steps

Troubleshooting

Configuration

​Webhook Endpoint

​Webhook Events

​Webhook Payload

​Request Headers

​Request Body

​Example Payload

​Signature Verification

​How Signatures Work

​Verification Process

​Test Mode Signatures

​Order Matching

​Lookup Process

​Stored Order Metadata

​Handling Webhook Responses

​Success Response

​Error Responses

​Debugging Webhooks

​Enable Logging

​Log Entries

​Common Issues

​Security Best Practices

Keep Secret Secure

Use HTTPS

Verify Signatures

Idempotency

​Retry Policy

​Next Steps

Troubleshooting

Configuration

Webhook Endpoint

Webhook Events

Webhook Payload

Request Headers

Request Body

Example Payload

Signature Verification

How Signatures Work

Verification Process

Test Mode Signatures

Order Matching

Lookup Process

Stored Order Metadata

Handling Webhook Responses

Success Response

Error Responses

Debugging Webhooks

Enable Logging

Log Entries

Common Issues

Security Best Practices

Retry Policy

Next Steps