Webhooks

Webhooks allow your application to receive real-time notifications about events in your Payonify account, enabling you to automate workflows and keep your systems in sync with the payment lifecycle.

How Webhooks Work

Setting Up Webhooks

1. Navigate to the Webhooks section in your Payonify dashboard
2. Enter your webhook endpoint URL (must be HTTPS in production)
3. Copy your webhook secret (whsec_xxxx) for signature verification
4. Save your configuration

Webhook Events

Payonify sends notifications for key payment lifecycle events:

Event Payload Structure

Code
 
{
  "id": "evt_wcmozs2wurgkcfe5jq4q",
  "type": "charge.succeeded",
  "object": "event",
  "created": 1763891091,
  "livemode": "false",
  "data": {
    "object": {
      "id": "ch_pujhja2l7plqtngoad76jdcs",
      "object": "charge",
      "status": "succeeded",
      "description": "Small Granite Chips",
      "amount": {
        "value": 6605,
        "currency": "usd"
      },
      "created": 1763891078,
      "paid": true,
      "livemode": "false",
      "payment_method": "mobile_money",
      "receipt_email": "Mathias_Hane@yahoo.com",
      "return_url": "http://example.com/success",
      "statement_descriptor": "ACME Store",
      "client_secret": "ch_xxx_secret_xxxxx",
      "cancelled_at": null,
      "cancellation_reason": null,
      "refund_reference": null,
      "failure_code": null,
      "failure_reason": null,
      "metadata": {
        "order_id": "7",
        "order_description": "Ergonomic Granite Shoes"
      },
      "shipping": {
        "name": "Caroline",
        "phone": "1-732-402-2396",
        "carrier": "Fedex",
        "tracking_number": "6n0hk430kpyuvl5dhb7f",
        "address": {
          "line1": "658 Goldner Spur",
          "line2": "Apt. 820",
          "city": "Aleenmouth",
          "province": "Texas",
          "country": "ZW"
        }
      },
      "payment_method_details": {
        "type": "mobile_money",
        "mobile_money": {
          "type": "c2b",
          "brand": "ecocash",
          "network": "Econet",
          "reference": "MP251123.0944.D60273",
          "customer_number": "771111111",
          "merchant_name": "Payonify Test Merchant",
          "merchant_code": "028538",
          "merchant_number": "789643586"
        }
      }
    }
  }
}

Payout Event Payload Example

Code
 
{
  "id": "evt_po_wcmozs2wurgkcfe5jq4q",
  "type": "payout.succeeded",
  "object": "event",
  "created": 1763891091,
  "livemode": "false",
  "data": {
    "object": {
      "id": "po_a7eryb3kdb6ljkzqe5vg3jbf",
      "object": "payout",
      "status": "paid",
      "description": "Monthly salary payment",
      "amount": {
        "value": 5000,
        "currency": "usd"
      },
      "created": 1763891078,
      "livemode": "false",
      "metadata": {
        "employee_id": "12345",
        "payment_type": "salary"
      },
      "destination_details": {
        "type": "mobile_money",
        "mobile_money": {
          "brand": "ecocash",
          "reference": "CI270218.0450.T0691170",
          "recipient_number": "771111111",
          "recipient_name": "John Doe",
          "channel_number": "789643586",
          "network": "Econet"
        }
      },
      "failure_code": null,
      "failure_message": null
    }
  }
}

Verifying Webhook Signatures

Every webhook includes a Payonify-Signature header that you must verify before processing the event.

Signature Header Format

Code
 
Payonify-Signature: t=1621267018,v1=5c52d36d49d6a2a243ca3dfe17fd9d4df3e04532d528528d46e13d0f2d2example

• t= — Unix timestamp when the webhook was sent
• v1= — HMAC-SHA256 signature

Verification Steps

1. Extract the timestamp (t) and signature (v1) from the header
2. Concatenate: {timestamp}.{raw_request_body}
3. Compute HMAC-SHA256 using your webhook secret
4. Compare your computed signature with the received signature
5. Verify the timestamp is within tolerance (recommended: 5 minutes)

Implementation Examples

const crypto = require('crypto');

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; // whsec_xxxx
const TOLERANCE_SECONDS = 300; // 5 minutes

function verifyWebhook(payload, signatureHeader) {
const parts = signatureHeader.split(',').reduce((acc, part) => {
  const [key, value] = part.split('=');
  acc[key] = value;
  return acc;
}, {});

const timestamp = parseInt(parts['t'], 10);
const receivedSignature = parts['v1'];

// Check timestamp tolerance
const now = Math.floor(Date.now() / 1000);
if (now - timestamp > TOLERANCE_SECONDS) {
  throw new Error('Webhook timestamp too old');
}

// Compute expected signature
const signedPayload = `${timestamp}.${payload}`;
const expectedSignature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(signedPayload)
  .digest('hex');

// Compare signatures (timing-safe)
if (!crypto.timingSafeEqual(
  Buffer.from(expectedSignature),
  Buffer.from(receivedSignature)
)) {
  throw new Error('Invalid webhook signature');
}

return JSON.parse(payload);
}

// Express.js example
app.post('/webhooks/payonify', express.raw({ type: 'application/json' }), (req, res) => {
try {
  const event = verifyWebhook(
    req.body.toString(),
    req.headers['payonify-signature']
  );

  switch (event.type) {
    case 'charge.succeeded':
      // Payment successful - fulfill order
      break;
    case 'charge.failed':
      // Payment failed - notify customer
      break;
  }

  res.status(200).send('OK');
} catch (err) {
  res.status(400).send('Webhook verification failed');
}
});

Handling Events

Retry Policy

If your endpoint doesn't respond with a 2xx status code, Payonify will retry delivery with exponential backoff:

After 10 failed attempts, the webhook is marked as failed.

Idempotency

Code
 
// Example: Track processed events
const processedEvents = new Set();

async function handleWebhook(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }

  // Process the event...

  processedEvents.add(event.id);
}

For production, store processed event IDs in your database with an appropriate TTL.

Security Best Practices

1. Always verify signatures — Never skip verification in production
2. Use HTTPS — Only expose webhook endpoints over HTTPS
3. Validate timestamps — Reject webhooks older than 5 minutes
4. Implement idempotency — Handle duplicate deliveries gracefully
5. Rotate secrets periodically — Update your webhook secret regularly
6. Log events — Keep audit logs for debugging and compliance

Troubleshooting