> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/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.
</Warning>

## New IP Addresses by Region

<Tabs>
  <Tab title="Singapore">
    **Region**: Asia Pacific (Singapore)

    ```
    52.77.130.167
    54.251.77.74
    54.255.59.189
    18.142.212.217
    ```
  </Tab>

  <Tab title="Europe (Frankfurt)">
    **Region**: Europe (Frankfurt)

    ```
    3.127.106.141
    3.65.238.41
    3.65.52.7
    3.77.135.138
    ```
  </Tab>

  <Tab title="United States">
    **Region**: North Virginia (US East)

    ```
    52.70.191.115
    100.24.154.219
    52.44.28.213
    52.72.76.90
    ```
  </Tab>
</Tabs>

<Info>
  **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).
</Info>

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

<CardGroup cols={2}>
  <Card title="Real-Time Analytics" icon="chart-line">
    Store webhook events to build custom analytics dashboards and track user engagement patterns
  </Card>

  <Card title="Content Moderation" icon="shield">
    Build automated message moderation and user management systems with instant event notifications
  </Card>

  <Card title="Search & Personalization" icon="magnifying-glass">
    Create custom search and personalization features based on real-time user activity data
  </Card>

  <Card title="Custom Integrations" icon="puzzle-piece">
    Integrate with external systems and build custom workflows triggered by platform events
  </Card>
</CardGroup>

## How Webhooks Work

<Info>
  **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.
</Info>

### Event-Driven Architecture

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Setup and Configuration

<Steps>
  <Step title="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.
  </Step>

  <Step title="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
  </Step>

  <Step title="Implement Webhook Receiver">
    Build your webhook endpoint to:

    * Accept HTTP POST requests
    * Verify webhook signatures
    * Process events and respond within 1.5 seconds
  </Step>

  <Step title="Test and Monitor">
    Test your webhook implementation and monitor delivery success rates and response times
  </Step>
</Steps>

### Configuration Limits

<CardGroup cols={2}>
  <Card title="Webhook Limit" icon="triangle-exclamation">
    **Maximum 10 webhooks per network**

    Recommended to keep webhook count reasonable for optimal performance and management
  </Card>

  <Card title="Response Time" icon="clock">
    **1.5 second timeout**

    Ensure your webhook endpoint responds quickly to prevent request timeouts and delivery failures
  </Card>
</CardGroup>

## 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.
</Warning>

<Tabs>
  <Tab title="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                                            |
  </Tab>

  <Tab title="Legacy Support">
    ### Backward Compatibility

    <Info>
      **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`.
    </Info>

    **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
  </Tab>
</Tabs>

## Available Events

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

### Event Categories

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Security" icon="shield">
    **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
  </Card>

  <Card title="Performance" icon="bolt">
    **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
  </Card>

  <Card title="Reliability" icon="check">
    **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
  </Card>

  <Card title="Scalability" icon="seedling">
    **Design for Scale**

    * Use queues for high-volume event processing
    * Implement rate limiting and backpressure handling
    * Scale webhook endpoints horizontally
    * Cache frequently accessed data
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

<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.
</Tip>