Skip to main content
Webhooks let your application receive HTTP POST notifications when events happen in your YuvexPay account, such as a payment being confirmed or a withdrawal completing.

​
Setting up webhooks

  1. Go to Settings > Webhooks in the dashboard.
  2. Click Add webhook and enter your endpoint URL.
  3. Select the events you want to receive.
  4. Save the webhook secret for signature verification.

​
Event types

EventDescription
PAYMENT_CONFIRMEDPayment has been confirmed by the provider.
PAYMENT_PAIDPayment is complete and funds are received.
PAYMENT_EXPIREDPayment expired before being completed.
PAYMENT_REFUNDEDA refund was processed for this payment.
PAYMENT_REFUND_FAILEDA refund attempt failed.
PAYMENT_CHARGEBACKA chargeback was filed against this payment.
MED_RECEIVEDA MED (mediation dispute) was received.
MED_RESOLVEDA MED dispute was resolved.
WITHDRAWAL_REQUESTEDA withdrawal was created and is being processed.
WITHDRAWAL_SENTA withdrawal was successfully sent.
WITHDRAWAL_FAILEDA withdrawal failed to process.

​
Webhook payload

Events are delivered as JSON POST requests to your endpoint: 
{
  "id": "evt_abc123",
  "type": "PAYMENT_PAID",
  "data": {
    "id": "pay_xyz789",
    "txId": "YVX-20260414-ABC",
    "status": "PAID",
    "amount": 49.90
  }
}

​
Headers

Each webhook request includes these headers:
HeaderDescription
X-Webhook-SignatureHMAC signature for verification.
X-Webhook-EventThe event type (e.g., PAYMENT_PAID).
X-Webhook-Delivery-IdUnique delivery ID for deduplication.
User-AgentYuvexPay-Webhook/1.0
Content-Typeapplication/json

​
Verifying signatures

Every webhook includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret. 
import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post("/webhook", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  // Process the event
  const { type, data } = req.body;
  console.log(`Received ${type}:`, data);

  res.status(200).send("OK");
});
Always verify the webhook signature before processing events. Never trust the payload without verification.

​
Retry behavior

If your endpoint doesn’t return a 2xx status code, YuvexPay retries the delivery with exponential backoff:
AttemptDelay
1st retry5 seconds
2nd retry10 seconds
3rd retry20 seconds
After all retries are exhausted, the delivery is marked as FAILED. You can monitor delivery status and retry failed deliveries from the dashboard.

​
Best practices

  • Return 200 quickly. Process webhook events asynchronously. Return a 200 status immediately and handle the business logic in a background job.
  • Handle duplicates. Use the X-Webhook-Delivery-Id header to deduplicate events. The same event may be delivered more than once.
  • Verify before trusting. Always validate the X-Webhook-Signature before acting on a webhook event.
  • Use HTTPS. Webhook endpoints must use HTTPS in production.