07 webhooks

Webhooks notify your server when events occur in Stablix. Use them to automate order fulfillment, update your database, and sync with your systems.

Setup

Configure Webhook URL

POST /merchants/webhook

{
  "url": "https://yoursite.com/webhooks/stablix",
  "events": [
    "invoice.paid",
    "invoice.released",
    "dispute.opened"
  ]
}

Response

{
  "success": true,
  "message": "Webhook configured. Save your webhook secret now.",
  "data": {
    "webhook_secret": "whsec_abc123def456..."
  }
}

Save the webhook_secret. It's only shown once and is required to verify webhook signatures.

---

Webhook Events

Invoice Events

Event	Description
invoice.created	Invoice created
invoice.paid	Payment received, funds in escrow
invoice.released	Funds released to merchant
invoice.refunded	Invoice refunded
invoice.expired	Payment deadline passed

Subscription Events

Event	Description
subscription.created	Subscription created
subscription.approved	Subscriber approved spending
subscription.activated	Subscription activated
subscription.charged	Successful charge
subscription.charge_failed	Charge failed
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed
subscription.cancelled	Subscription cancelled

Dispute Events

Event	Description
dispute.opened	Dispute opened
dispute.evidence_submitted	Evidence added
dispute.status_changed	Status updated
dispute.resolved	Dispute resolved

---

Webhook Payload

All webhooks follow this structure:

{
  "event": "invoice.paid",
  "data": {
    "invoice_id": "inv_abc123",
    "amount": 99.99,
    "currency": "USDC",
    "chain": "solana",
    "status": "paid",
    "payment": {
      "tx_hash": "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp...",
      "from_address": "buyer_wallet_address",
      "confirmed_at": "2024-01-15T11:30:00Z"
    }
  },
  "timestamp": "2024-01-15T11:30:00Z"
}

---

Verifying Signatures

Every webhook includes a signature header. Always verify signatures before processing webhooks.

Headers

Header	Description
X-Stablix-Signature	HMAC-SHA256 signature
X-Stablix-Timestamp	Unix timestamp
X-Stablix-Delivery-ID	Unique delivery ID
X-Stablix-Event	Event type

Verification Process

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  // Check timestamp (prevent replay attacks)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old');
  }

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

  // Compare signatures
  if (signature !== expectedSignature) {
    throw new Error('Invalid signature');
  }

  return JSON.parse(payload);
}

Example Handler (Express)

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

const app = express();

// Use raw body for signature verification
app.post('/webhooks/stablix', 
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-stablix-signature'];
    const timestamp = req.headers['x-stablix-timestamp'];
    const payload = req.body.toString();

    try {
      // Verify signature
      const signedPayload = `${timestamp}.${payload}`;
      const expectedSignature = crypto
        .createHmac('sha256', process.env.STABLIX_WEBHOOK_SECRET)
        .update(signedPayload)
        .digest('hex');

      if (signature !== expectedSignature) {
        return res.status(401).send('Invalid signature');
      }

      // Parse and handle event
      const event = JSON.parse(payload);
      
      switch (event.event) {
        case 'invoice.paid':
          handleInvoicePaid(event.data);
          break;
        case 'invoice.released':
          handleInvoiceReleased(event.data);
          break;
        // ... handle other events
      }

      res.status(200).send('OK');
    } catch (error) {
      console.error('Webhook error:', error);
      res.status(400).send('Webhook error');
    }
  }
);

function handleInvoicePaid(data) {
  console.log(`Invoice ${data.invoice_id} paid!`);
  // Update order status, send confirmation email, etc.
}

function handleInvoiceReleased(data) {
  console.log(`Invoice ${data.invoice_id} released!`);
  // Mark order as complete
}

---

Retries

If your endpoint returns an error (non-2xx status) or times out, Stablix retries the webhook:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

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

---

Webhook Deliveries

List Deliveries

GET /webhooks/deliveries

Query Parameters

Parameter	Type	Description
status	string	pending, delivered, failed
event	string	Filter by event type
page	number	Page number
limit	number	Items per page

Response

{
  "success": true,
  "data": [
    {
      "delivery_id": "del_abc123",
      "event": "invoice.paid",
      "status": "delivered",
      "attempts": 1,
      "response": {
        "status_code": 200
      },
      "delivered_at": "2024-01-15T11:30:05Z",
      "created_at": "2024-01-15T11:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150
  }
}

Get Delivery Details

GET /webhooks/deliveries/:deliveryId

Response

{
  "success": true,
  "data": {
    "delivery_id": "del_abc123",
    "event": "invoice.paid",
    "payload": {
      "event": "invoice.paid",
      "data": { ... }
    },
    "url": "https://yoursite.com/webhooks/stablix",
    "status": "delivered",
    "attempts": 1,
    "response": {
      "status_code": 200,
      "body": "OK"
    },
    "delivered_at": "2024-01-15T11:30:05Z"
  }
}

Retry Delivery

Manually retry a failed webhook:

POST /webhooks/deliveries/:deliveryId/retry

Response

{
  "success": true,
  "message": "Webhook retry queued"
}

Webhook Stats

GET /webhooks/stats

Response

{
  "success": true,
  "data": {
    "total": 1500,
    "delivered": 1480,
    "failed": 15,
    "pending": 5,
    "success_rate": 98.67
  }
}

---

Testing Webhooks

Local Development

Use a tunnel service to receive webhooks locally:

# Using ngrok
ngrok http 3000

# Set webhook URL to ngrok URL

# https://abc123.ngrok.io/webhooks/stablix

Test Events

Use test mode API keys to create test invoices. Test payments trigger real webhooks to your endpoint.

---

Best Practices

1

Return quickly

Process webhooks asynchronously. Return 200 immediately, then handle the event in a background job.

2

Handle duplicates

Use X-Stablix-Delivery-ID to deduplicate. The same event may be delivered multiple times.

3

Verify signatures

Always verify webhook signatures to prevent spoofing.

4

Use HTTPS

Webhook URLs must use HTTPS in production.

5

Monitor failures

Set up alerts for failed webhooks.

6

Implement idempotency

Your handlers should be idempotent. Processing the same webhook twice should have the same result.

Example: Idempotent Handler

async function handleInvoicePaid(data) {
  const { invoice_id, payment } = data;
  
  // Check if already processed
  const existing = await db.orders.findOne({
    stablix_invoice_id: invoice_id,
    status: 'paid'
  });
  
  if (existing) {
    console.log(`Invoice ${invoice_id} already processed`);
    return;
  }
  
  // Update order
  await db.orders.updateOne(
    { stablix_invoice_id: invoice_id },
    { 
      status: 'paid',
      payment_tx: payment.tx_hash,
      paid_at: payment.confirmed_at
    }
  );
  
  // Send confirmation email
  await sendOrderConfirmation(invoice_id);
}

---

Remove Webhook

DELETE /merchants/webhook

This removes your webhook configuration. You'll stop receiving webhook notifications.