← Back to Dashboard

Developer Guide

Integrate Ninja Backer tips into your applications, overlays, and automation tools.

Webhook Integration

Configure a webhook URL in your dashboard to receive HTTP POST requests when tips arrive.

Webhook Payload

{
  "type": "tip",
  "amount": 5.00,
  "currency": "USD",
  "name": "TipperName",
  "message": "Great stream!",
  "timestamp": 1702138446000
}

Payload Fields

Field	Type	Description
type	string	Always "tip"
amount	number	Tip amount in dollars (e.g., 5.00)
currency	string	Currency code (USD, EUR, GBP, etc.)
name	string	Tipper's display name
message	string	Optional message from tipper
timestamp	number	Unix timestamp in milliseconds

Webhook Signature (Optional)

For added security, you can enable HMAC-SHA256 signatures on outgoing webhooks. When enabled, each webhook includes a signature header:

X-NinjaBacker-Signature: t=1703721600,v1=abc123def456...

Generate a Webhook Secret

Go to your Dashboard, expand the Webhook section, and click Generate to create a webhook secret.

Store this secret securely — you'll need it to verify incoming webhooks.

Verifying Signatures (Node.js)

const crypto = require('crypto');

function verifyWebhook(body, signatureHeader, secret) {
  const [tPart, v1Part] = signatureHeader.split(',');
  const timestamp = tPart.split('=')[1];
  const expectedSig = v1Part.split('=')[1];

  // Reject stale webhooks (>5 minutes old)
  if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) {
    return false;
  }

  const signedPayload = `${timestamp}.${JSON.stringify(body)}`;
  const computedSig = crypto.createHmac('sha256', secret)
    .update(signedPayload).digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computedSig),
    Buffer.from(expectedSig)
  );
}

// Usage in Express/Fastify:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-ninjabacker-signature'];
  if (sig && !verifyWebhook(req.body, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process verified webhook...
});

Server-Sent Events (SSE)

For real-time integrations, connect to the SSE endpoint using your Tip ID.

Endpoint

GET https://tip.vdo.ninja/v1/subscribe/{YOUR_TIP_ID}

JavaScript Example

const tipId = 'your_tip_id_here';
const events = new EventSource(`https://tip.vdo.ninja/v1/subscribe/${tipId}`);

events.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'tip') {
    console.log(`Received $${data.amount} from ${data.fromLabel}`);
    console.log(`Message: ${data.message}`);
  }
};

events.onerror = () => {
  console.log('Connection lost, reconnecting...');
};

SSE Event Format

{
  "type": "tip",
  "amount": 5.00,
  "currency": "USD",
  "fromLabel": "TipperName",
  "message": "Great stream!",
  "timestamp": 1702138446000
}

VDO.Ninja Integration

Add the &tip=YOUR_TIP_ID parameter to your VDO.Ninja URL to enable in-stream tipping.

https://vdo.ninja/?push=streamid&tip=YOUR_TIP_ID

URL Parameters

Parameter	Description	Example
&tip=ID	Your Tip ID from dashboard	&tip=aS_WnIp8IPrV
&tip	Show setup modal (no ID)	&tip
&tipqrsize=N	QR code size in pixels	&tipqrsize=200
&tipqr	Show QR code on video (default: on)	&tipqr=false
&tipamounts=A,B,C	Custom tip button amounts	&tipamounts=5,10,25,50
&tipcurrency=XXX	Currency code	&tipcurrency=EUR

For Viewers

Viewers must opt-in to see tip UI. Add &showtips to viewer URLs:

https://vdo.ninja/?view=streamid&showtips

Hiding the QR Code

If you prefer not to show the QR code overlay on your video:

https://vdo.ninja/?push=streamid&tip=YOUR_TIP_ID&tipqr=false

Custom QR Code Size

Adjust the QR code size (default is 150px):

https://vdo.ninja/?push=streamid&tip=YOUR_TIP_ID&tipqrsize=100

Social Stream Integration

To use with Social Stream, enter your Social Stream webhook URL in the dashboard. Tips will appear alongside your chat messages.

Testing

Use the "Send Test Tip" button in your dashboard to trigger a test notification without making a real payment. Test tips include "isTest": true in the payload.

Profile Avatar

Your profile avatar is automatically loaded from Gravatar using your Stripe account email.

Setting Up Your Avatar

1. Go to gravatar.com and create an account
2. Use the same email address you used when registering with Stripe
3. Upload your profile picture
4. Your avatar will automatically appear on your tip page

If no Gravatar is found, a default placeholder image is displayed.