Webhook Ingress API

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

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 can push messages from multiple platforms (YouTube, Twitch, TikTok, etc.) directly to your chat room.

Setup Instructions

1. Open Social Stream Ninja extension settings
2. Navigate to the Custom Actions or API Integration section
3. Add a new HTTP POST action with:
   • URL: https://api.ninjachatter.com/rooms/YOUR_ROOM_ID/ingress
   • Header: Authorization: Bearer YOUR_API_KEY
   • Content-Type: application/json
4. Map the SSN message fields to the payload format:

   {
     "type": "chat",
     "payload": {
       "text": "{message}",
       "displayName": "{author}",
       "userId": "{authorId}",
       "source": "{platform}",
       "avatar": "{authorPhoto}"
     }
   }

SSN Field Mapping

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