Webhooks

Webhooks let you receive real-time HTTP notifications when events occur in SilentChat — for example when a new conversation starts, a message is sent, or a contact is created.

Setting Up Webhooks

1. In your dashboard go to Settings → Webhooks.
2. Click Add Endpoint.
3. Enter the URL of your server endpoint (must be HTTPS).
4. Select the events you want to subscribe to (or choose All Events).
5. Save. SilentChat will generate a signing secret for this endpoint — copy it and store it securely.

Available Events

Payload Format

SilentChat sends a POST request to your endpoint with a JSON body:

{
  "id": "evt_01HXY3ABC",
  "type": "message.created",
  "tenant_id": "tn_abc123",
  "created_at": "2025-10-12T14:35:00Z",
  "data": {
    "conversation_id": "conv_01HXYZ",
    "message_id": "msg_01HXYZ",
    "sender_type": "visitor",
    "text": "Hi, I need help with my order."
  }
}

Headers

Verifying Signatures

Every webhook request includes an X-SilentChat-Signature header containing an HMAC-SHA256 hex digest of the raw request body, computed with your endpoint’s signing secret. You should always verify this signature before processing the event.

Node.js Example

const crypto = require('crypto');

function verifySignature(secret, body, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

// In your request handler:
app.post('/webhooks/silentchat', (req, res) => {
  const signature = req.headers['x-silentchat-signature'];
  const rawBody = req.rawBody; // raw request body as a string

  if (!verifySignature(process.env.SC_WEBHOOK_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Process the event ...

  res.status(200).send('OK');
});

Python Example

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

app = Flask(__name__)

def verify_signature(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route('/webhooks/silentchat', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-SilentChat-Signature', '')
    raw_body = request.get_data()

    if not verify_signature(os.environ['SC_WEBHOOK_SECRET'], raw_body, signature):
        abort(401)

    event = request.get_json()
    print(f"Received event: {event['type']}")

    # Process the event ...

    return 'OK', 200

Retry Policy

If your endpoint does not return a 2xx status code (or does not respond within 10 seconds), SilentChat will retry the delivery:

After 3 failed attempts the delivery is marked as failed. You can view failed deliveries and manually retry them from the Webhooks settings page in your dashboard.

If an endpoint consistently fails for 7 days, it will be automatically disabled and you will receive an email notification.

Best Practices

• Respond quickly. Return a 200 as soon as you receive the event and process it asynchronously.
• Verify signatures on every request to prevent spoofed events.
• Handle duplicates. Use the X-SilentChat-Delivery header to detect and ignore duplicate deliveries.
• Use HTTPS. Webhook endpoints must use TLS.