Learn about WebHook

อัพเดทล่าสุด :2023-03-14

WebHook is the channel through which customers receive their sending information. After the user sends the mail request to EngageLab, EngageLab will synchronously return the "request result" to the user, and the "send result" and "other event results" of the mail are returned to the user asynchronously through WebHook.

Processing of WebHook

  • EngageLab provides customers with some email events, and customers can choose to focus on some events.
  • When an event occurs, EngageLab will be triggered to send data (POST) to the URL set by the customer.
  • Data type pushed by EngageLab: "Content Type: application/json".
  • The customer receives the data and parses the event and data. You need to return HTTP Status Code 200 within 3s. Otherwise, EngageLab will resend the message.

Usage Method

  • The user writes the HTTP service to enable it to handle the corresponding events, parse the relevant data, and open the corresponding URL.
  • The user selects the concerned event in the 'WebHook' of EngageLab and configures the URL to receive data.

Signature Verification

To ensure that the source identity of the message is EngageLab, you can choose to perform security authentication on the source of POST data (It is also possible to directly parse POST data without verification)

The method of safety certification is as follows :

  • Get APP SECRET through 【Send Settings】-【WebHook】
  • Parse the X-WebHook-Timestamp in the Header
  • Parse the X-WebHook-AppKey in the Header
  • Parse the X-WebHook-Signature in the Header
  • Use md5(timestamp+appkey+secret) to generate signature signature, compare with X-WebHook-Signature

Response Processing

After receiving the callback from EngageLab, the developer service needs to respond within 3 seconds according to the following requirements.

Successful reception: the HTTP response status code needs to return 200 or 204, and no response message needs to be returned.

Receiving failure: HTTP response status code needs to be returned to 5XX or 4XX, and response message needs to be returned at the same time, with the format as follows:


Parameter Type Required/Optional Description
code int Optional Error code
message string Optional Error details

Retry Processing

If you encounter a URL access error or timeout, EngageLab will retry at most 7 times The maximum time interval between each retry is 3min, 10min, 30min, 1h, 6h, 12h and 24h That is, you have enough time to repair the URL before the message is lost.

If the number of retries is exceeded, EngageLab will discard the message.

For each event processing and data analysis, you need to return "Successful response received" within 3s. Otherwise, EngageLab will resend this message.

Contact Sales