Webhook Ingress API

Push messages to your chat room from external services, bots, and integrations.

Using Social Stream Ninja?

SSN has built-in Ninja Chatter support. Just copy your API key and enable the toggle in SSN.

Quick Setup

Endpoint

Authentication

Two authentication methods are supported:

1. API Key (Recommended)

Include your room's API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Find your API key in the Dashboard under "Bot & Webhook Integration" for each room.

2. HMAC Signature

Sign the request body using HMAC-SHA256 with your webhook secret:

X-Chat-Signature: sha256=COMPUTED_SIGNATURE

Request Body

Payload Fields - Core

Payload Fields - Badges

Payload Fields - Donations

Payload Fields - Memberships

Payload Fields - Events

Payload Fields - Additional

Top-Level Meta Field

{
  "type": "chat",
  "payload": { ... },
  "meta": {
    "customField": "value",
    "anyOtherData": 123
  }
}

Examples

Simple Message

curl -X POST "https://api.ninjachatter.com/rooms/YOUR_ROOM_ID/ingress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "chat",
    "payload": {
      "text": "Hello from my bot!"
    }
  }'

Message with User Info

curl -X POST "https://api.ninjachatter.com/rooms/YOUR_ROOM_ID/ingress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "chat",
    "payload": {
      "text": "Check out this stream!",
      "displayName": "StreamBot",
      "userId": "bot-123",
      "source": "twitch",
      "sourceIcon": "https://example.com/twitch-icon.png",
      "avatar": "https://example.com/bot-avatar.png"
    }
  }'

Super Chat / Donation

curl -X POST "https://api.ninjachatter.com/rooms/YOUR_ROOM_ID/ingress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "chat",
    "payload": {
      "text": "Great stream! Keep it up!",
      "displayName": "GenerousViewer",
      "userId": "viewer-456",
      "source": "youtube",
      "donation": "$10.00",
      "donationValue": 10.00,
      "backgroundColor": "#1565c0",
      "textColor": "#ffffff"
    }
  }'

Event (Raid, Follow, etc.)

curl -X POST "https://api.ninjachatter.com/rooms/YOUR_ROOM_ID/ingress" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "text": "",
      "displayName": "BigStreamer",
      "event": "raid",
      "title": "RAID",
      "subtitle": "123 viewers"
    }
  }'

Response

Social Stream Ninja Integration

Social Stream Ninja has built-in support for Ninja Chatter. Push messages from YouTube, Twitch, TikTok, and 30+ platforms directly to your chat room with just a few clicks.

Quick Setup (2 Steps)

Share with Your Audience

Once connected, share your chat link with viewers:

https://ninjachatter.com/YOUR_ROOM_ID

Viewers can watch chat from all your platforms in one place, without needing accounts or the SSN extension.

Advanced: Custom HTTP Integration

For developers building custom integrations or needing more control, you can send messages directly via HTTP POST:

Content Filtering & Moderation

Messages sent via webhook ingress are subject to the same filtering and moderation as regular chat messages.

Bad Word Filter

Moderation Actions

Room moderators can take action on webhook users just like regular users:

• Ban - Permanently block a user ID from the room
• Mute - Temporarily silence a user (with duration)
• Stealth Ban - User appears to send messages but they're not broadcast

Rate Limits

Security Best Practices

• Keep your API key secret - Never expose it in client-side code.
• Rotate keys regularly - Use the "Rotate Key" button in the dashboard if you suspect a leak.
• Enable chat filtering - Turn on the bad word filter in room settings to prevent abuse.
• Use user IDs consistently - Helps moderation actions work across sessions.

Related Documentation

• Developer API - Read-only stream endpoints for overlays
• OBS Overlay Guide - Build custom chat overlays

Need Help?

If you have questions or need assistance with your integration:

• Social Stream Ninja: socialstream.ninja
• GitHub: Report an issue