Matching result callback API¶

When the matching is complete, the Hive server requests the callback API from the developer's server to deliver the matching results and receive the response value.

The order for delivering the matching results by requesting the callback API is as follows.

Select match integration method as server callback in the Hive console
Register the developer server URL to receive callbacks in the Hive console
Upon completion of matching, the Hive server requests the callback API to the developer server to deliver the matching result
If the developer server receives the matching result successfully, return HTTP response status code (HttpStatus 200) to the Hive server

Request URL (Developer Server URL)¶

Register the developer server URL that will receive the matching results by requesting the callback API in the Hive console as the API endpoint. This URL must be a publicly accessible address from the outside.

Header parameters¶

The header values when making a callback API request are as follows.

Field Name	Description	Type	Required
X-Match-Signature	Signature value encrypted with HMAC SHA-256 algorithm for the transmitted data	string	Y

Note

You can determine the authenticity of the matching result through the X-Match-Signature value.

The value of X-Match-Signature can be obtained using the example code below (Java), and the HMAC SHA-256 key value used in the code can be found in the Hive console.

```java
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class MatchSignature {  
    private static final String HMAC_SHA_256 = "HmacSHA256";
    private static final String UTF_8 = "UTF-8";
    public String getSignature(String secret, String httpRequestBody) throws Exception {
            SecretKeySpec key = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
            Mac mac = Mac.getInstance(HMAC_SHA_256);
            mac.init(key);
            byte[] source = httpRequestBody.getBytes(UTF_8);

            return new String(Base64.getEncoder().encode(mac.doFinal(source)), StandardCharsets.UTF_8);
    }
}
```

Body parameters (Matching results delivered via callback API)¶

The matching result data transmitted during the callback API request is as follows.

Field Name	Description	Type
gameIndex	The gameIndex value of the completed match	int
matchId	The matchId value of the completed match	int
matchingInfos	An array of information about app users who completed the match, users with a `playerId` field of `0` are treated as bots matchingId: Match id privateInfos: An array of information about users matched in a private match, in the same format as timeoutPlayerInfos teamInfos: An array of information about users matched in a team match (teamIndex: team number, playerInfos: an array of information about team members in the same format as timeoutPlayerInfos)	json
timeoutPlayerInfos	An array of information about app users who timed out without matching extraData: extraData entered during the matching request point: point entered during the matching request playerId: user playerId entered during the matching request	json

Callback API request example (Hive Server → Developer Server)¶

curl --location 'HIVE 콘솔에 등록한 앱 개발사 API 엔드포인트' --header 'Content-Type: application/json' --header 'X-Match-Signature: nj2YlgGTlLXcAhrl6ijSgfD71gTWokBiM8WPn72xxg8=' --data '{
   "gameIndex": 1,
   "matchId": 1,
   "matchingInfos": [
       {
           "matchingId": "1:1_2024-06-05T05:43:28.91_1",
           "privateInfos": [
               {
                   "playerId": 100,
                   "point": 1000
               },
               {
                   "playerId": 101,
                   "point": 1000
               }
           ]
       }
   ],
   "timeoutPlayerInfos": []
}'

Return value¶

If the matching results delivered by the Hive server through the callback API request are successfully received by the developer's server, it should return HttpStatus 200 as a response.

According to the response from the developer's server, it is processed in the following way on the Hive server.

HttpStatus 200 response: It is determined that the matching result has been successfully completed, and the corresponding callback API request is terminated.
Response with a value other than HttpStatus 200 or Timeout: The callback API will be requested again at regular intervals to deliver the matching result.
No HttpStatus 200 response or no other response value: If there is continuously no response, the matching result will not be delivered for a certain period from a system management perspective.