Orangepill Cloud

Webhooks

Receive real-time notifications when events happen in your Orangepill account. Webhooks are HTTP callbacks sent to your server.

What webhooks do

  • Notify you when payments succeed or fail
  • Alert you to wallet balance changes
  • Track customer journey events
  • Trigger automated workflows

Quick setup

curl https://api.orangepill.cloud/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/orangepill",
    "events": [
      "payment.succeeded",
      "payment.failed",
      "wallet.balance_updated",
      "customer.created"
    ]
  }'

Example webhook payload

{
  "id": "evt_abc123",
  "type": "payment.succeeded",
  "created": 1642080000,
  "data": {
    "id": "preq_xyz789",
    "amount": 50000,
    "currency": "COP",
    "status": "succeeded",
    "payment_method": "bre_b",
    "metadata": {
      "order_id": "order_123"
    }
  }
}

Verify webhook signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Available events

Payments

  • payment.succeeded - Payment completed successfully
  • payment.failed - Payment failed or declined
  • payment.pending - Payment awaiting confirmation
  • payment.refunded - Payment refunded

Wallets

  • wallet.created - New wallet created
  • wallet.balance_updated - Balance changed
  • wallet.transaction_created - New transaction

Customers

  • customer.created - New customer record
  • customer.updated - Customer details changed

Retry behavior

  • Failed webhooks retry with exponential backoff
  • Maximum 3 retry attempts
  • 1 minute, 5 minutes, 15 minutes

Testing webhooks

Use webhook testing tools:

  • webhook.site
  • ngrok for local development
  • Orangepill dashboard webhook logs

Next steps