​
Webhook Events

Infrastructure Update - Action Required by June 9, 2025We are updating the list of IP addresses used by our webhook service as part of our ongoing efforts to enhance infrastructure security and reliability.What’s Changing:
  • A new set of IP addresses will be introduced for webhook traffic
  • Current IP addresses will be deprecated and stop working after June 9, 2025
Action Required: Update your firewall or allowlist configurations to include the new IP addresses before June 9, 2025 to ensure uninterrupted webhook delivery.

​
New IP Addresses by Region

Region: Asia Pacific (Singapore)
52.77.130.167
54.251.77.74
54.255.59.189
18.142.212.217
Need Help? If you have questions or need assistance with the IP address update, contact our support team at [email protected] or submit a request through the social.plus Help Center.

​
Overview

Webhook Events provide a powerful way to extend social.plus functionality by receiving real-time triggers from the platform. When enabled, events from your Chat and Social SDK are forwarded to your system instantly, enabling custom integrations and automation.

Real-Time Analytics

Store webhook events to build custom analytics dashboards and track user engagement patterns

Content Moderation

Build automated message moderation and user management systems with instant event notifications

Search & Personalization

Create custom search and personalization features based on real-time user activity data

Custom Integrations

Integrate with external systems and build custom workflows triggered by platform events

​
How Webhooks Work

Webhook vs Traditional API: Unlike traditional APIs where your application makes requests to receive responses, webhooks are “reverse APIs” where social.plus initiates communication by sending data to your system as soon as events occur.

​
Event-Driven Architecture

​
Setup and Configuration

1

Enable Webhook Feature

Submit a request through the social.plus Help Center to enable webhooks (currently in Private Beta). Processing takes approximately 5 business days.
2

Configure Webhook URLs

Admin users can create and manage webhooks in the admin panel:
  • Add webhook URLs for event delivery
  • Configure event types and filters
  • Set up authentication and security
3

Implement Webhook Receiver

Build your webhook endpoint to:
  • Accept HTTP POST requests
  • Verify webhook signatures
  • Process events and respond within 1.5 seconds
4

Test and Monitor

Test your webhook implementation and monitor delivery success rates and response times

​
Configuration Limits

Webhook Limit

Maximum 10 webhooks per networkRecommended to keep webhook count reasonable for optimal performance and management

Response Time

1.5 second timeoutEnsure your webhook endpoint responds quickly to prevent request timeouts and delivery failures

​
Security and Authentication

​
Signature Verification

Security Requirement: Always verify the x-amity-signature header before processing webhook events to prevent request forgery and ensure data integrity.

​
Delivery Headers

All webhook HTTP POST requests include these headers:
HeaderDescription
x-amity-signatureHMAC Base64 digest of the response body using SHA-256 hash function
User-AgentIdentifies the webhook delivery system
Content-TypeAlways application/json
Content-LengthSize of the JSON payload

​
Webhook Implementation Example

​
Sample Webhook Request

POST /your-webhook HTTP/1.1
Host: your-domain.com
x-amity-signature: <HMAC Base64 Digest>
User-Agent: Social-Plus-Webhooks/1.0
Content-Type: application/json
Content-Length: 442

{
  "event": "channel.didCreate",
  "data": {
    "userIds": ["user123"],
    "channel": {
      "isDistinct": false,
      "type": "standard",
      "metadata": {},
      "tags": [],
      "isMuted": false,
      "lastActivity": "2024-12-01T09:35:23.816Z",
      "updatedAt": "2024-12-01T09:35:23.815Z",
      "createdAt": "2024-12-01T09:35:23.815Z",
      "isRateLimited": false,
      "rateLimitWindow": 1000,
      "channelId": "channel-abc123",
      "memberCount": 1,
      "messageCount": 0
    },
    "users": [
      {
        "displayName": "John Doe",
        "updatedAt": "2024-12-01T11:39:19.615Z",
        "createdAt": "2024-11-01T09:33:57.811Z",
        "userId": "user123",
        "roles": ["member"],
        "flagCount": 0,
        "hashflag": { "bits": 0, "hashes": 0, "hash": [] }
      }
    ]
  }
}

​
Webhook Handler Implementation

const express = require('express');
const crypto = require('crypto');
const app = express();

// Middleware to capture raw body for signature verification
app.use('/webhook', express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-amity-signature'];
  const payload = req.body;
  
  // Verify signature
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Parse and process the event
  const event = JSON.parse(payload);
  console.log('Received event:', event.event);
  
  // Process the event based on type
  switch (event.event) {
    case 'channel.didCreate':
      handleChannelCreated(event.data);
      break;
    case 'message.didCreate':
      handleMessageCreated(event.data);
      break;
    // Add more event handlers
  }
  
  // Respond with 200 status
  res.status(200).json({});
});

​
Available Events

Complete Event Reference: For a full list of available webhook events and their detailed payload structures, please check our API Reference documentation.

​
Event Categories

​
Best Practices

Security

Always Verify Signatures
  • Implement signature verification for all webhooks
  • Use constant-time comparison to prevent timing attacks
  • Keep webhook secrets secure and rotate regularly
  • Log suspicious or invalid requests

Performance

Optimize Response Times
  • Respond within 1.5 seconds to prevent timeouts
  • Process events asynchronously when possible
  • Implement proper error handling and logging
  • Monitor webhook performance and delivery rates

Reliability

Handle Failures Gracefully
  • Implement retry logic for failed processing
  • Handle duplicate events appropriately
  • Store events for replay in case of system failures
  • Monitor webhook health and alert on issues

Scalability

Design for Scale
  • Use queues for high-volume event processing
  • Implement rate limiting and backpressure handling
  • Scale webhook endpoints horizontally
  • Cache frequently accessed data

​
Troubleshooting

​
Support and Resources

Technical Support

Need help with webhook implementation? Contact our support team at [email protected]

Help Center

Visit the social.plus Help Center for additional resources and guides

API Reference

Check our API Reference for complete event documentation and payload details

Community Forum

Join our developer community to share experiences and get help from other developers
Getting Started: Start with a simple webhook handler that logs all events, then gradually add processing logic for specific event types relevant to your use case.