Setting Up Webhooks

Available via: API only (private key)

What Are Webhooks?

Webhooks let your server receive automatic HTTP POST notifications when specific events occur — such as a new payment being created or a payment status changing (authorized, settled, failed, refunded, etc.).

Instead of polling the API for updates, webhooks push data to your server as events happen.

Supported events: Inflow currently fires two event types: payment_created and payment_status_updated. Subscription-related payments also trigger these events (with subscriptionId populated in the payload).

How It Works

1. You register a webhook endpoint URL via the Inflow API.
2. When an event occurs, Inflow sends an HTTP POST request to your URL with the event data.
3. Your server processes the event and returns a 200 status code to acknowledge receipt.

Creating a Webhook (API Only)

Webhook management is done entirely via the API using your private key.

curl -X POST https://api.inflowpay.xyz/api/webhook \
  -H "X-Inflow-Api-Key: inflow_priv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/inflow"
  }'

Response

{
  "webhookId": "wh_abc123",
  "webhookUrl": "https://yourserver.com/webhooks/inflow",
  "secret": "whsec_your_webhook_secret"
}

Save the secret! It is only returned once at creation time. You'll need it to verify webhook signatures.

Limits

• You can register up to 5 webhook endpoints per account.
• Webhook URLs must use HTTPS — HTTP is not accepted.
• Inflow validates your URL with a HEAD request before creating the webhook.

Delivery & Retries

Inflow uses Svix to deliver webhooks. If your endpoint does not return a 2xx within 15 seconds, the delivery is retried with exponential backoff — up to 10 attempts spread over several hours to days.

Your endpoint must consistently return HTTP 2xx. If it keeps failing, Inflow will automatically disable your webhook after exhausting all retry attempts. You can check the failure reason via the webhook status endpoint and re-enable it via the update status endpoint once the issue is fixed.

Webhook Endpoint Requirements

Your webhook endpoint must:

• Accept HTTP POST requests
• Use HTTPS (HTTP is not supported)
• Return a 2xx status code within 15 seconds
• Parse the JSON body to process the event

Example Server (Node.js / Express)

const express = require('express');
const app = express();

app.post('/webhooks/inflow', express.json(), (req, res) => {
  const { data } = req.body;

  for (const event of data) {
    const { eventType, payload } = event;

    switch (eventType) {
      case 'payment_created':
        console.log('New payment:', payload.id);
        break;
      case 'payment_status_updated':
        console.log(`Payment ${payload.id} → ${payload.status}`);
        break;
      default:
        console.log('Unknown event type:', eventType);
    }
  }

  res.status(200).json({ received: true });
});

app.listen(3000);