Webhook Ingress API

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

Using Social Stream Ninja?

Relay SSN chat into NinjaChatter with the room ingress API key, or display a room in an SSN dock. See setup, verification, and limitations below.

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 exact request bytes using HMAC-SHA256 with your webhook secret. Encode the digest as Base64, with no sha256= prefix:

X-Chat-Signature: BASE64_HMAC_SHA256

For text-only bots, create a send-only bot key in the dashboard’s Integrations section. Use it in X-API-Key or Authorization: Bearer. It cannot delete messages or mint privileged tokens. See the automation guide for its restricted payload, key management, signing examples, response handling, and retry limitations. Existing SSN ingress keys keep their current permissions.

Request Body

Deleting a message

Use the message_id returned by ingress to remove a displayed message. Send the same room authentication as for chat:

{ "type": "delete", "payload": { "target_id": "MESSAGE_ID" } }

The target can also be supplied as a top-level target_id. Chat and WebSocket overlays handle these events and the moderation event delete_message with payload.message_id. Repeating a deletion or targeting a message no longer displayed has no effect.

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.

SSN → NinjaChatter: relay incoming chat

Share with Your Audience

Once connected, share your chat link with viewers:

https://ninjachatter.com/YOUR_ROOM_ID

Viewers do not need the SSN extension. Joining and sending chat follow the room’s guest/provider settings. A public read-only overlay requires the room to be enabled and Allow read-only stream access to be on; guest access is a separate setting.

NinjaChatter → SSN: display a room

To show this room in an SSN dock, use the SSN-format read-only stream and dock URL. This connects the dock directly to NinjaChatter. It does not import a source into the SSN extension, merge an existing SSN session, or send replies back to Twitch/YouTube. Use NinjaChatter’s normal chat page when viewers should participate.

Verify and troubleshoot

• Nothing arrives: first check that a new ordinary text message appears in SSN itself, then check the relay toggle and ingress key. The normal relay path skips bot-tagged messages and event-tagged rows and applies SSN duplicate/relay checks. Do not use a membership event, bot response, or image-only message as the first test.
• Key rejected: copy the key from the room’s Social Stream Ninja panel again. A send-only bot key is for /rooms/{room}/ingress, not the built-in /ssn relay. Replace the saved SSN key after ingress-key rotation.
• Still no message: inspect the extension background request to https://api.ninjachatter.com/ssn. Its current relay does not report HTTP failures in the popup. Check status and response body, but redact authorization headers before sharing logs.
• Accepted but invisible: a message_id of filtered without external_id means filtering blocked publication. Check the destination room and display permissions. A successful HTTP response is not a viewer-delivery receipt.
• Repeated messages: enable one intended forwarding path. The SSN relay skips sources tagged socialstreamchat, but that is not a general loop guarantee for custom adapters. Preserve provenance and prevent your own publications from being relayed back.
• Disconnects under load: reconnect with bounded backoff and jitter. Streams are live, with no durable replay guarantee. Host slow mode limits individual chat senders; it is not an aggregate throttle for the SSN webhook relay. See the failure-handling guide before retrying writes.

Keep the ingress key in your private SSN configuration or integration backend, never in an overlay URL or public page. SSN exports may contain it. For a custom text-only bot, prefer the restricted send-only bot key.

Built-in relay HTTP contract

POST https://api.ninjachatter.com/ssn takes Authorization: Bearer ROOM_INGRESS_API_KEY, Content-Type: application/json, and the envelope below. The key identifies the destination room. This endpoint does not accept a send-only bot key, JWT, or HMAC signature in place of the ingress key. The request body limit is 65,536 bytes. Check every HTTP response; do not automatically retry an ambiguous publication because repeated requests can duplicate messages.

{
  "type": "chat",
  "payload": {
    "text": "Hello from SSN",
    "displayName": "Example viewer",
    "userId": "example-viewer-1",
    "source": "youtube"
  }
}

The built-in adapter converts SSN messages to this envelope; posting a raw SSN row is not the same contract. Its usual relay path forwards chat text, not every SSN event. HTML chat content is cleaned to text. Rich fields are supported selectively and are not guaranteed to survive every downstream display; the SSN read-only adapter is a smaller format than the ingress payload.

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