Webhook & Send API

Overview

The Webhook & Send API add-on gives you programmatic access to the ChatGenius messaging layer. It has two complementary parts:

You can use these independently or together. A common pattern: receive events via webhook, process them in your own system, and send replies back through the Send-Reply API.

Getting Started

Requirements

• An active ChatGenius subscription on the Creator, Professional, or Business plan
• The Webhook & Send API add-on purchased from your portal (Add to plan →)
• A publicly accessible HTTPS endpoint to receive events (for webhook forwarding)

Portal setup

1. Log in to your ChatGenius portal
2. Navigate to Integrations in the left sidebar
3. Scroll to the Webhook & Send API section
4. Enter your HTTPS endpoint URL and select which event types to receive
5. Generate your API key (used to authenticate Send-Reply API calls)
6. Copy your signing secret (used to verify incoming webhook events)
7. Complete the data-sharing attestation and toggle the webhook to Enabled

Webhook Forwarding

When an event occurs, ChatGenius makes a POST request to your configured HTTPS endpoint with a signed JSON payload and a User-Agent: SumGenius-Webhook/1.0 header.

Delivery behavior

• Your endpoint must respond with HTTP 2xx within the configured timeout (default 10 seconds, configurable up to 30 seconds)
• Any non-2xx response or timeout is treated as a failure and retried automatically
• The same X-SumGenius-Delivery-Id (the event's stable unique ID) is used across all retry attempts for the same event
• Events that exhaust all retry attempts are dead-lettered and can be manually retried from the portal

Retry schedule

Failed deliveries are retried on the following fixed schedule (up to 6 attempts total by default):

Event Types

You can filter which event types get forwarded to your endpoint in the portal. If no event type filters are configured, all supported event types are forwarded.

The active event type is included in the X-SumGenius-Event request header on every delivery.

Event Payload

Every event is a JSON object posted to your endpoint with Content-Type: application/json.

{
  "event_id":    "a3f8e1c2d4b567890abcdef01234567",
  "event_type":  "message.received",
  "occurred_at": "2026-02-20T08:15:00Z",
  "source": {
    "platform": "instagram",
    "channel":  "meta_dm"
  },
  "conversation": {
    "id": 10482
  },
  "customer": {
    "platform_user_id":       "17841400123456789",
    "platform_user_name":     "Jane Doe",
    "platform_user_username": "janedoe"
  },
  "message": {
    "id":          "mid.1234567890abcdef",
    "text_raw":    "Hi, do you have availability next Tuesday?",
    "attachments": []
  },
  "meta": {
    "version":         "v1",
    "payload_profile": "full",
    "generated_at":   "2026-02-20T08:15:00Z"
  }
}

Payload fields

Attachment fields

Verifying Signatures

Every webhook delivery includes signature headers so you can confirm it came from ChatGenius and the payload hasn't been tampered with. Always verify the signature before processing an event.

Request headers sent by ChatGenius

Signature algorithm

The signed string is the Unix timestamp and the raw JSON request body joined by a period:

signed_string = timestamp + "." + raw_request_body
signature     = HMAC-SHA256(signed_string, your_signing_secret)
header_value  = "sha256=" + hex(signature)

Compare the computed value to the X-SumGenius-Signature header using a constant-time comparison to prevent timing attacks. Also verify the timestamp is within a reasonable window (we recommend ±300 seconds) to prevent replay attacks.

// Read the raw body BEFORE json_decode()
$rawBody   = file_get_contents('php://input');
$secret    = $_ENV['CHATGENIUS_WEBHOOK_SECRET'];
$sigHeader = $_SERVER['HTTP_X_SUMGENIUS_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_SUMGENIUS_TIMESTAMP']  ?? '';

// Reject requests older than 5 minutes
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(400);
    exit('Timestamp out of window');
}

$signedString = $timestamp . '.' . $rawBody;
$expected     = 'sha256=' . hash_hmac('sha256', $signedString, $secret);

if (!hash_equals($expected, $sigHeader)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Signature valid — safe to process
$event = json_decode($rawBody, true);

const crypto = require('crypto');

// Use express.raw() to preserve the raw body buffer
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret     = process.env.CHATGENIUS_WEBHOOK_SECRET;
  const sigHeader  = req.headers['x-sumgenius-signature'] ?? '';
  const timestamp  = req.headers['x-sumgenius-timestamp']  ?? '';

  // Reject requests older than 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Timestamp out of window');
  }

  const signedString = `${timestamp}.${req.body.toString()}`;
  const expected     = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signedString)
    .digest('hex');

  const expectedBuf = Buffer.from(expected);
  const headerBuf   = Buffer.from(sigHeader);
  const valid = expectedBuf.length === headerBuf.length
    && crypto.timingSafeEqual(expectedBuf, headerBuf);
  if (!valid) return res.status(401).send('Invalid signature');

  // Signature valid — acknowledge immediately
  res.sendStatus(200);

  const event = JSON.parse(req.body.toString());
  // process event asynchronously...
});

import hmac, hashlib, time, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    secret     = os.environ['CHATGENIUS_WEBHOOK_SECRET'].encode()
    sig_header = request.headers.get('X-SumGenius-Signature', '')
    timestamp  = request.headers.get('X-SumGenius-Timestamp', '')

    # Reject requests older than 5 minutes
    if abs(time.time() - float(timestamp)) > 300:
        abort(400, 'Timestamp out of window')

    raw_body      = request.get_data()
    signed_string = f"{timestamp}.{raw_body.decode()}".encode()
    expected      = 'sha256=' + hmac.new(
        secret, signed_string, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig_header):
        abort(401, 'Invalid signature')

    event = request.get_json()
    return '', 200

Send-Reply API

Use the Send-Reply API to send messages or reactions from your server back to a customer's conversation on Facebook or Instagram.

Authentication

All Send-Reply API requests must include your API key, generated in the portal under Integrations → Webhook & Send API. Keys are prefixed with sgwh_.

Pass the key using either header:

# Option A — custom header (recommended)
X-SumGenius-Api-Key: sgwh_your_api_key_here

# Option B — standard Bearer token
Authorization: Bearer sgwh_your_api_key_here

Action: send_message

Send a text message to a customer in an existing conversation. This is the default action when action is omitted.

Request body

curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "confirm-appt-10482-001",
    "conversation_id": 10482,
    "message_text": "Your appointment is confirmed for Tuesday at 2pm. See you then!"
  }'

const response = await fetch('https://sumgenius.ai/api/meta/webhook-send.php', {
  method: 'POST',
  headers: {
    'X-SumGenius-Api-Key': process.env.CHATGENIUS_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    idempotency_key: 'confirm-appt-10482-001',
    conversation_id: 10482,
    message_text: 'Your appointment is confirmed for Tuesday at 2pm. See you then!'
  })
});

const result = await response.json();

$payload = json_encode([
    'idempotency_key' => 'confirm-appt-10482-001',
    'conversation_id' => 10482,
    'message_text'    => 'Your appointment is confirmed for Tuesday at 2pm. See you then!'
]);

$ch = curl_init('https://sumgenius.ai/api/meta/webhook-send.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-SumGenius-Api-Key: ' . getenv('CHATGENIUS_API_KEY'),
        'Content-Type: application/json'
    ]
]);

$result = json_decode(curl_exec($ch), true);

Action: react

Add an emoji reaction to a specific message. Use the message.id from a received webhook event as the target_message_id.

Request body

Supported reaction values

For action=react, send one of these reaction values in the reaction field:

If reaction is omitted for action=react, ChatGenius defaults it to love. For action=unreact, do not send reaction.

curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "react",
    "idempotency_key": "react-10482-msg-001",
    "conversation_id": 10482,
    "target_message_id": "mid.1234567890abcdef",
    "reaction": "love"
  }'

Action: unreact

Remove a previously added reaction from a message.

Request body

curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "unreact",
    "idempotency_key": "unreact-10482-msg-001",
    "conversation_id": 10482,
    "target_message_id": "mid.1234567890abcdef"
  }'

Action: typing_on

Show a typing indicator (the "..." bubble) to the customer. The indicator lasts approximately 20 seconds or until you send a message, whichever comes first. Useful for signaling that your system is processing a reply.

Request body

curl -X POST https://sumgenius.ai/api/meta/webhook-send.php \
  -H "X-SumGenius-Api-Key: sgwh_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "typing_on",
    "idempotency_key": "typing-10482-1709500000",
    "conversation_id": 10482
  }'

Idempotency

Every Send-Reply API request requires an idempotency_key. If you submit the same key again, the original result is returned without resending — making retries safe under network failures.

• Max length: 128 characters
• A duplicate submission returns "status": "duplicate" with the original result
• A reliable key pattern: {your-reference}-{conversation_id}-{sequence}

Response Format

All responses are JSON with Content-Type: application/json.

Success response

{
  "success":         true,
  "status":          "sent",
  "request_id":      "msgreq_...",
  "conversation_id": 10482,
  "platform":        "instagram",
  "action":          "send_message",
  "sent_at":         "2026-02-20 08:15:32",
  "message":         "Message sent successfully."
}

Response fields

Status values

External Reply Mode

By default, ChatGenius AI/automation can still respond to incoming DMs even when webhook forwarding is active. External Reply Mode applies a runtime override for Facebook/Instagram DMs so your external system becomes the sole responder for those DM conversations.

When to use it

• You have your own AI or support system and want full control over every response
• You need to route different conversation types to different handlers
• You want ChatGenius purely as a message delivery and forwarding layer

How to enable

Toggle External Reply Mode in your portal under Integrations → Webhook & Send API. The change takes effect immediately.

Payload Profiles

Choose how much customer data is included in forwarded events. Configure your profile in the portal under Integrations → Webhook & Send API.

The active profile is reflected in meta.payload_profile on every event.

Error Reference

Errors always return "success": false with an error string describing what went wrong.

{
  "success": false,
  "status":  "error",
  "error":   "message_text is required for action=send_message."
}

HTTP status codes

Limits

Message length

Webhook delivery

Platform rate limits

Outbound messages go through Meta's Messenger API. Meta enforces rate limits per connected account:

If Meta returns a rate limit error, the request is automatically queued for retry using the schedule above.