Webhooks

Receive real-time notifications when important events happen in your gateway, delivered securely to your endpoints via HTTP POST.

Quickstart

Create a webhook endpoint on your server to listen to Nolxy events. Then, register your endpoint URL and copy the generated webhook secret to verify payloads.

// Your server endpoint receiving webhooks
app.post('/nolxy-webhooks', (req, res) => {
  const payload = req.body;
  
  if (payload.event === 'quota.warning') {
    console.log(`User ${payload.userId} is nearing quota!`);
  }
  
  res.status(200).send('OK');
});

Reference

Supported Events

quota.warning

Triggered when a user reaches 90% of their monthly request quota. Includes current usage and limit.

quota.exceeded

Triggered when the monthly quota is fully consumed. Requests will be rejected until the next billing cycle.

circuit.open

Triggered when a circuit breaker opens due to backend failures. Includes route ID and failure count.

circuit.closed

Triggered when a circuit breaker recovers and closes. Includes route ID and recovery time.

api_key.created

Triggered when a new API key is created. Includes key metadata (never the key itself).

api_key.revoked

Triggered when an API key is revoked due to abuse or manual action.

Payload Format

All webhooks follow a consistent JSON structure.

{
  "event": "quota.warning",
  "userId": 42,
  "data": {
    "currentUsage": 90000,
    "limit": 100000,
    "percentage": 90
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Delivery & Retries

  • If your endpoint fails to process the webhook (non-2xx response), Nolxy will retry delivery up to 3 times with exponential backoff (5s, 10s, 20s).
  • You must respond with a 2xx Status Code within 5 seconds, or it is considered a failure.
  • Your endpoint is prevented from resolving to internal IP addresses.

Examples

Verifying the Webhook Signature

Every webhook includes an X-Nolxy-Signature header. Use it to verify the request authentically originated from Nolxy.

import crypto from 'crypto';

// Get the raw request payload string and the signature header
const signature = req.headers['x-nolxy-signature'];

function verifyWebhook(rawPayload, signature, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawPayload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Common Errors

Signature Verification Failing

Invalid Raw Payload

Fix: When hashing the payload, you must use the exact raw JSON string that was received from Nolxy. If your framework automatically parses JSON into an object and you try to serialize it back to string, the format may change and break the signature check.

Plan Requirements

Webhooks are available on paid plans.

Circuit BreakersOpenAPI Import