Webhook Events

Webhook Events is a great way you can extend and build custom functionalities on your own by receiving triggers from Social Plus. When enabled, events that happen within your Chat and Social SDK are forwarded to your system in real-time. By receiving these events you can build and extend your own functions such as

1. Storing those events to build your own analytic dashboard

2. Build a custom message moderation or automatic banning system

3. Build custom search and personalization functionalities based on user activities forwarded to your analytic system.

A webhook can also be termed as a type of API that is driven by events rather than requests. Instead of one application making a request to another to receive a response, a webhook is a service that allows one program to send data to another as soon as a particular event takes place. Webhooks are sometimes referred to as “reverse APIs,” because communication is initiated by the application sending the data rather than the one receiving it.

To receive these events you will need to set up a Webhook system as detailed below.

Setup

When an event is triggered, an HTTP POST payload is sent to the Webhook's configured URL. Webhooks can serve various purposes such as creating push notifications, backup logging or even building external applications based on Webhook events.

• Admin users can create new Webhooks in the admin panel by using the URL.

• Admin users can delete selected Webhooks in the admin panel as well.

• We recommend having no more than 10 Webhooks per network.

• All Webhooks will be triggered near-real-time as the events occur. Please seeEvents for list of events available.

• To preserve system performance, all webhook HTTP requests will timeout in 1.5 seconds - please make sure your webhook receiver responds back within the interval to prevent losing any requests.

• Upon receiving the webhook, the system should return with the response status code of 200 with an empty JSON response.

The webhook feature is currently in Private Beta. Please submit your request to the Social Plus Help Center to enable this feature. It will take approximately 5 business days to process your request.

Delivery Headers

The HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain the following headers:

Header	Description
x-amity-signature	the HMAC Base64 digest of the response body. The HMAC Base64 digest is generated by performing SHA-256 hash function with the secret key as the HMAC key, JSON request body as the payload and digested as Base64 string.

Please make sure you verify x-amity-signature header by calculating HMAC Base64 signature of the payload with the secret key of your corresponding webhook endpoint before processing the event to prevent request forgery.

To maintain legacy support, you may receive 2 requests per event with another request containing x-eko-signature - you may ignore this request.

Example Delivery

POST /your-webhook HTTP/1.1
x-amity-signature: <HMAC Base64 Digest>
User-Agent: node-superagent/4.0.0
Content-Type: application/json
Content-Length: 442
{
  "event": "channel.didCreate",
  "data": {
    "userIds": ["A"],
    "channel": {
      "isDistinct": false,
      "type": "standard",
      "metadata": {},
      "tags": [],
      "isMuted": false,
      "lastActivity": "2018-11-30T09:35:23.816Z",
      "updatedAt": "2018-11-30T09:35:23.815Z",
      "createdAt": "2018-11-30T09:35:23.815Z",
      "isRateLimited": false,
      "rateLimitWindow": 1000,
      "channelId": "testWebhook",
      "memberCount": 0,
      "messageCount": 0
    },
    "users": [
      {
        "displayName": "A",
        "updatedAt": "2018-11-30T11:39:19.615Z",
        "createdAt": "2018-11-01T09:33:57.811Z",
        "userId": "A",
        "roles": [],
        "flagCount": 0,
        "hashflag": { "bits": 0, "hashes": 0, "hash": [] }
      }
    ]
  }
}

Events

Once webhook is activated, you will start receiving events on a near-real-time basis. Please check our API Reference for the full list of events and their payload.

Deprecation Notices

From 20 June 2022, we have deprecated the following legacy webhook events:

• message.created

• channel.created

• channel.joined

• channel.membersAdded

• v3.video-streaming.didRecord

• v3.video-streaming.didStart

• v3.video-streaming.didStop

As these webhook events were only accessible internally, this deprecation should have no impact on our current customers. For a list of events that we currently support, please refer to our API Reference.