ZyPayDocs
Webhooks

Real-time Event Notifications

Stay informed about payment events with ZyPay webhooks. Receive instant notifications when payments are completed, failed, or refunded.

What are Webhooks?

Real-time Event Notifications

Webhooks allow ZyPay to send real-time notifications to your application when specific events occur

How it works:

1

You register a webhook endpoint URL with ZyPay

2

When an event occurs, ZyPay sends an HTTP POST request to your endpoint

3

Your application processes the event and responds with HTTP 200

Benefits:

Real-time notifications
No polling required
Reliable delivery
Secure verification

Available Events

payment.completed

green

Payment was successfully completed

payment.failed

red

Payment failed or was declined

payment.pending

yellow

Payment is pending approval

refund.completed

blue

Refund was successfully processed

subscription.created

purple

New subscription was created

subscription.cancelled

orange

Subscription was cancelled

customer.created

teal

New customer was created

webhook.test

gray

Test webhook for verification

Setting up Webhooks

1

Create Webhook Endpoint

Create an HTTP endpoint in your application to receive webhook events:

Node.js Express Example
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/zypay', (req, res) => {
  const event = req.body;
  
  // Process the webhook event
  switch (event.type) {
    case 'payment.completed':
      console.log('Payment completed:', event.data);
      break;
    case 'payment.failed':
      console.log('Payment failed:', event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  // Always respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});
2

Register Webhook with ZyPay

Register your webhook endpoint with ZyPay using the API:

Register Webhook
curl -X POST https://api.zypay.com/v1/webhooks \
  -H "Authorization: Bearer sk_test_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/zypay",
    "events": [
      "payment.completed",
      "payment.failed",
      "refund.completed"
    ],
    "secret": "your_webhook_secret"
  }'
3

Verify Webhook Signature

Always verify webhook signatures to ensure the request came from ZyPay:

Signature Verification
const crypto = require('crypto');

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

app.post('/webhooks/zypay', (req, res) => {
  const signature = req.headers['zy-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  // Process the webhook event
  const event = req.body;
  console.log('Received webhook:', event.type);
  
  res.status(200).send('OK');
});

Webhook Payload

Event Structure

All webhook events follow the same structure

Webhook Event Payload
{
  "id": "evt_1234567890",
  "type": "payment.completed",
  "created": "2024-01-15T10:30:00Z",
  "data": {
    "id": "pay_1234567890",
    "status": "completed",
    "amount": {
      "value": 1000,
      "currency": "USD"
    },
    "customer": {
      "id": "cust_1234567890",
      "email": "customer@example.com"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}

Headers

  • Content-Type: application/json
  • User-Agent: ZyPay-Webhooks/1.0
  • Zy-Signature: sha256=...
  • Zy-Event-Id: evt_1234567890

Response

  • Respond with 200 OK to acknowledge
  • Response body is ignored
  • Timeout: 30 seconds
  • Retry: Up to 3 times

Security Best Practices

Do

  • Always verify webhook signatures
  • Use HTTPS endpoints only
  • Respond quickly (under 30 seconds)
  • Handle duplicate events idempotently
  • Log events for debugging

Don't

  • Ignore signature verification
  • Use HTTP endpoints
  • Process events synchronously
  • Return error status codes
  • Trust event data without validation

Testing Webhooks

Webhook Testing Tools

Test your webhook endpoints before going live

ZyPay Webhook Tester

Use our built-in webhook testing tool to send test events to your endpoint

Open Tester

ngrok for Local Testing

Expose your local development server to receive webhooks

ngrok http 3000

Troubleshooting

Ready to Set Up Webhooks?

Start receiving real-time notifications for your payment events. Set up webhooks in minutes with our comprehensive documentation.

View API ReferenceTest Webhooks