Events subscription

For games and applications, it is possible to get information about ongoing events on OK in real time.

In the moment when a specific event happens on OK, a message with information on that event will be sent to a special URL (also known as webhook) via an HTTP POST request.

This way, you can receive information on events via the long polling API. The method: events.updates;

How to enable it

You can manage this option in the application settings in the Event Subscription Settings block:

For event sending to work, do the following:

  • enter the address of a service that will receive requests with events in the Webhook Link field;
  • complete the confirmation process for your webhook with help of a special confirmation request (see below);
  • compile a list of events that you want to receive on your webhook;
  • save settings of your application.

Several minutes later, your webhook will start receiving events you selected.

Webhook confirmation

You need to confirm the webhook, so that we could send you messages about ongoing events.

To confirm it, do the following:

  • enter the address in the Webhook Link field;
  • prepare the webhook for reception of a verification request;
  • press the “Confirm” button to check the webhook.

When processing the verification request for your webhook, make sure that it is not blocked because of CORS. You need to permit receiving requests on your webhook from the nap.okapps.ru domain. To do this, you have to send headers Access-Control-Allow-Origin and Access-Control-Allow-Headers when receiving request from this domain.

During the validation, we send a following request:

  • POST request
  • Content-type: application/json
  • Request body: {“webhookType”: “CONFIRMATION”}

A following answer is expected:

  • response code: 200
  • Content-type: application/html or application/text
  • Answer body: a string listed in the settings

How to receive messages

When an event on OK you subscribed to in the game settings is executed, a message in an HTTP request form will be sent. We send following requests:

  • POST request
  • Content-type: application/json
  • UserAgent of the request: OK/1.0 Webhook API
  • Request body: is determined by the event type

Your service should return the response code 200 as an answer to our request.

Types of events

Your webhook will receive messages with various bodies that depend on the type of an event.

At the moment, following event types are available:

  • events related to joining a group/leaving a group
  • events related to allowing/forbidding to send messages from the group

Events that happened in the official group of the game or the application are processed.

To enable this feature, you need the following:

  • an official group on OK;
  • an application/a game on OK;
  • your group should be linked to the game/the application as the official game group.

You can link the group in the “Official group” field in the application settings.

Joining / leaving the game group

The message body when a user joins the group

{
"type": "JOIN",
"timestamp": 1618250409915,
"userId": "user:1234567890",
"userName": "First name, Last name",
"groupId": "group:1234567890123456",
"webhookType": "GROUP"
}

The message body when a user leaves the group

{
"type": "LEAVE",
"timestamp": 1618250409915,
"userId": "user:1234567890",
"userName": "First name, Last name",
"groupId": "group:1234567890123456",
"webhookType": "GROUP"
}

Subscription to messages from the game group

The message body when a user enables messages from the group

{
"type": "MESSAGES_ON",
"timestamp": 1618250409915,
"userId": "user:1234567890",
"userName": "First name, Last name",
"groupId": "group:1234567890123456",
"webhookType": "GROUP"
}

The message body when a user disables messages from the group

{
"type": "MESSAGES_OFF",
"timestamp": 1618250409915,
"userId": "user:1234567890",
"userName": "First name, Last name",
"groupId": "group:1234567890123456",
"webhookType": "GROUP"
}

Subscription to game reviews

The message body when a user adds a review for a game

{
"prevComment": "",
"webhookType": "APP",
"prevRating": 0,
"appId": "app:123123123",
"type": "RATING_COMMENT",
"timestamp": 1691947736017,
"rating": 5,
"userName": "First Name, Last Name",
"comment": "Game is great!",
"userId": "user:123123123"
}