Skip to main content

Webhooks​

Introduction to Webhooks​

Webhooks are calls initiated from Midasbuy to the developer's server during user operations on Midasbuy. Webhooks provide an opportunity for real-time interaction with the developer's server during the user's purchase process. Developers can further process user product information, including restricting user purchases, recommending specific products to users, etc. Currently, Midasbuy has implemented basic capabilities such as user verification, product verification, order notifications, and more. In the future, Midasbuy will further expand webhook capabilities to facilitate cooperation between Midasbuy and developers, providing users with a better experience.

Receiving and Processing​

For webhook notification responses, the following conventions are observed:

Receive ResultHTTP Code ConventionResponse Message Format Convention
Receive Successful200Set processed to true
Receive Failed500Set processed to false

For errors with a 500 code, synchronous and asynchronous events have different processing methods:

  • Synchronous Events

Terminate the process and prompt the user that an exception occurred and a retry is needed.

  • Asynchronous Events

If Midasbuy's call to the developer's server times out or returns an error, Midasbuy will retry. The retry interval strategy is 1s, 1m, 10m, 30m, 1h, 6h, 12h, 24h, 168h.

Verifying Signatures​

Midas will include the signature of the callback message in the callback's HTTP headers. Merchants must verify the callback's signature to ensure that the callback is sent by Midas.

Constructing a Signature String​

First, the merchant obtains the following information from the response:

  • The response timestamp from the HTTP header Txgw-Timestamp.
  • The response nonce from the HTTP header Txgw-Nonce.
  • The response body.

Then, construct the response signature verification string according to the following rules. The signature string consists of three lines, ending with \n at the end of each line, including the last line. \n is a newline character (ASCII code value 0x0A). If the response message body is empty (such as an HTTP status code of 204 No Content), the last line is only a \n newline character.

Response Timestamp\n
Response Nonce\n
Response Body\n

For example, if a response's HTTP message is:

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 02 Apr 2019 12:59:40 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2204
Connection: keep-alive
Keep-Alive: timeout=8
Content-Language: zh-CN
Request-ID: e2762b10-b6b9-5108-a42c-16fe2422fc8a
Txgw-Nonce: NONCE1234567890
Txgw-Signature: iRwHQ5FNt3KFv5nR0a7VFvFoGCCJA4ea330+Nb1LsBODDxmnNfz+/AaV/3QvF1nODzCDtwIo+1fMZlvcYVfKzldVYMi9uXp2crY116RxHnU5L2OcvM/IIudvZBUSOxDiaWPH79VO6+9dlccAKZ8eP2Zu9Svd9F95RWAaG/g72cIQDGmf7nyqAOopy1dz4Q/ZF7/1EsBlvPo5LyY521DCnbEq80FGf0nCR5vDplfV4PoYaI0jZ+qcHSB4hc1FOIIizcecI28sR22af0boO3F4Q98+jLRXxEyhYY/loijVkv6N+ZcEWs6C1ksy80a9/VyoxUhBP2O9HOPPcDwd4I/fOA==
Txgw-Timestamp: 1725519185
Cache-Control: no-cache, must-revalidate

{"id":"WEBHOOK240929CBXLYDCHMKXXE","create_time":"2024-09-18T14:40:09+08:00","update_time":"2024-09-18T14:40:09+08:00","resource":{"app_id":"145000000","user_id":"user_id1","server_id":"1"},"resource_type":"RESOURCE_TYPE_USER","resource_version":"1.0","event_version":"1.0","event_type":"USER_VALIDATE"}

Then the signature verification string is:

1725519185
NONCE1234567890
{\"id\":\"WEBHOOK240929CBXLYDCHMKXXE\",\"create_time\":\"2024-09-18T14:40:09+08:00\",\"update_time\":\"2024-09-18T14:40:09+08:00\",\"resource\":{\"app_id\":\"145000000\",\"user_id\":\"user_id1\",\"server_id\":\"1\"},\"resource_type\":\"RESOURCE_TYPE_USER\",\"resource_version\":\"1.0\",\"event_version\":\"1.0\",\"event_type\":\"USER_VALIDATE\"}

Obtaining the Response Signature​

Midas's response signature is transmitted via the HTTP header Txgw-Signature. (Note: Due to formatting, the example may contain line breaks, but the actual data should be on one line.)

Txgw-Signature: nSbn5D/8NOhby7hoxDp7Ma+VnqSQm6K7/Pe6hXhjGV+NcmYkunJiovF+c87oaFua+W2tAuquyH6SZxLZ/FjKcG6GhhrlpuJnyb0dUfQ6UiehwSKs0omy1/wEb/ygwj4AFJZts1z5B0s95ErX4rk6H51FTy4akOjmr6XSgeLvz1tYzcKV6aZk1N66fbRJAozNn148T32JrWY2I5RYR7byLX9c/sHxiBD+6L93/Zj+KLE5ub95iBc9M+V7zsvs/MplME30Ks+JDyg29HCkZ7tSS25VzeCDxovGNMZ5MmDq4xQSYC6fH9qO41GP9E1iakKdt1V+6zyI52Z6/7h3FPjeeA==

Use Base64 decoding on the value of Txgw-Signature to obtain the response signature.

Some proxy servers or CDN service providers might "filter out" Midas's extended HTTP headers during forwarding, causing the application layer to be unable to retrieve Midas's signature information. When merchants encounter such situations, Midasbuy recommend adjusting the proxy server configuration or directly connecting to Midas's server to receive notifications.