> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Events

> Real-time event notifications system for extending social.plus functionality with custom integrations and analytics

> [!WARNING]
>
> **Infrastructure Update - Action Required by June 9, 2025**
>
> We 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

**Singapore**

**Region**: Asia Pacific (Singapore)

```
52.77.130.167
54.251.77.74
54.255.59.189
18.142.212.217
```

**Europe (Frankfurt)**

**Region**: Europe (Frankfurt)

```
3.127.106.141
3.65.238.41
3.65.52.7
3.77.135.138
```

**United States**

**Region**: North Virginia (US East)

```
52.70.191.115
100.24.154.219
52.44.28.213
52.72.76.90
```

> [!NOTE]
>
> **Need Help?** If you have questions or need assistance with the IP address update, contact our support team at [support@social.plus](mailto:support@social.plus) or submit a request through the [social.plus Help Center](https://help.social.plus).

## 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

> [!NOTE]
>
> **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

> **Event Triggers**
>
> **Real-Time Delivery**
>
> * Events are triggered instantly when actions occur in your social.plus application
> * HTTP POST payloads sent to your configured webhook URLs
> * Near-real-time delivery for immediate response capabilities
>
> **Event Types**
>
> * User actions (posts, comments, reactions)
> * Chat messages and channel events
> * Community and social interactions
> * Moderation and safety events

> **Webhook Characteristics**
>
> **Performance Considerations**
>
> * All webhook requests timeout in 1.5 seconds
> * Your webhook endpoint must respond within this interval
> * System should return HTTP 200 status with empty JSON response
>
> **Reliability Features**
>
> * Automatic retry mechanisms for failed deliveries
> * Signature verification for security
> * Scalable infrastructure for high-volume events

## Setup and Configuration

**1. Enable Webhook Feature**

Submit a request through our [support team](mailto:support@social.plus) 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 network**
>
> Recommended to keep webhook count reasonable for optimal performance and management

> **Response Time**
>
> **1.5 second timeout**
>
> Ensure your webhook endpoint responds quickly to prevent request timeouts and delivery failures

## Security and Authentication

### Signature Verification

> [!WARNING]
>
> **Security Requirement**: Always verify the `x-amity-signature` header before processing webhook events to prevent request forgery and ensure data integrity.

**Header Details**

### Delivery Headers

All webhook HTTP POST requests include these headers:

| Header | Description |
| - | - |
| `x-amity-signature` | HMAC Base64 digest of the response body using SHA-256 hash function |
| `User-Agent` | Identifies the webhook delivery system |
| `Content-Type` | Always `application/json` |
| `Content-Length` | Size of the JSON payload |

**Legacy Support**

### Backward Compatibility

> [!NOTE]
>
> **Legacy Header**: You may receive duplicate requests with `x-eko-signature` header for backward compatibility. You can safely ignore these requests and only process events with `x-amity-signature`.

**Migration Approach**

* Process events with `x-amity-signature` header
* Ignore duplicate events with `x-eko-signature`
* Update your systems to use the new signature format

## Available Events

> [!NOTE]
>
> **Complete Event Reference**: For a full list of available webhook events and their detailed payload structures, please check our [API Reference documentation](../../api-reference/).

### Event Categories

> **Chat Events**
>
> **Channel Events**
>
> * `channel.didCreate` - New channel created
> * `channel.didUpdate` - Channel settings updated
> * `channel.didDelete` - Channel deleted
>
> **Message Events**
>
> * `message.didCreate` - New message sent
> * `message.didUpdate` - Message edited
> * `message.didDelete` - Message deleted
> * `message.didFlag` - Message flagged for moderation

> **Social Events**
>
> **Post Events**
>
> * `post.didCreate` - New post published
> * `post.didUpdate` - Post edited
> * `post.didDelete` - Post deleted
> * `post.didReact` - Reaction added to post
>
> **Comment Events**
>
> * `comment.didCreate` - New comment added
> * `comment.didUpdate` - Comment edited
> * `comment.didDelete` - Comment deleted

> **User Events**
>
> **User Actions**
>
> * `user.didCreate` - New user registered
> * `user.didUpdate` - User profile updated
> * `user.didFollow` - User followed another user
> * `user.didJoinCommunity` - User joined community
>
> **Moderation Events**
>
> * `user.didFlag` - User reported/flagged
> * `user.didBan` - User banned from platform
> * `user.didUnban` - User ban lifted

## 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

> **Common Issues**
>
> **Webhook Not Receiving Events**
>
> * Verify webhook URL is accessible from social.plus servers
> * Check firewall rules allow traffic from social.plus IP addresses
> * Ensure webhook endpoint responds with HTTP 200 status
> * Verify webhook is properly configured in admin panel
>
> **Signature Verification Failures**
>
> * Confirm you're using the correct webhook secret
> * Verify signature calculation matches expected format
> * Check for character encoding issues in payload
> * Ensure raw request body is used for signature verification

> **Performance Issues**
>
> **Timeout Problems**
>
> * Optimize webhook handler for sub-1.5 second response
> * Move heavy processing to background jobs
> * Implement proper database connection pooling
> * Add monitoring and alerting for response times
>
> **High Volume Handling**
>
> * Implement event queuing and batch processing
> * Scale webhook endpoints horizontally
> * Use caching for frequently accessed data
> * Consider implementing backpressure mechanisms

> **Debugging Tips**
>
> **Testing Webhooks**
>
> * Use tools like ngrok for local development testing
> * Implement comprehensive logging for webhook events
> * Test with different event types and payloads
> * Monitor webhook delivery success rates
>
> **Monitoring and Alerts**
>
> * Set up alerts for webhook failures
> * Monitor response times and error rates
> * Log all webhook events for debugging
> * Implement health checks for webhook endpoints

> [!TIP]
>
> **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.