WebHook

WebHook Integration Guidelines

Note: To integrate the Webhook API, please contact the customer success team (provide the webhook configuration address and type). Alternatively, you can configure it yourself via the related webhook APIs.

1. Interaction Flow

2. API Security Guidelines

Please contact the administrator to obtain the secret key and company id (available in the admin backend).

• Encryption Method 1 (Recommended)

With this API encryption method, the encrypted fields are placed in the request headers ( header ).

1. Use tenant_id + timestamp + secret key as the signature string (access_token), and compute the signature using the HmacSHA256 algorithm.

    String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
    String tenantId = "500975";
    String timestamp = "1666942813620";
    String message = tenantId + timestamp ;
    String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
    // 小写
    // str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5

• Encryption Method 2

With this API encryption method, the encrypted fields are placed in the request body ( body ).

1. Use tenant_id + timestamp + secret key as the signature string (access_token), and compute the signature using the HmacSHA256 algorithm.

    String appSecret = "f9a40a4780f5e1306c46f1c8daecee3b";
    String tenantId = "500975";
    String timestamp = "1666942813620";
    String message = tenantId + timestamp ;
    String access_token = HmacSHA256Util.hmacSHA256(appSecret,message);
    // 小写
    // str = df98eda524132837317c5ea7e4f67ef4224dedc3f01548b6cb211b08eb0328c5

Note: For integrations after June 2024, all use the first encryption method (parameters passed via headers).

For java HmacSHA256 encryption, you can reference the common-codec(1.15) package.

    public static String hmacSha256(String apikey, String message) {
        return (new HmacUtils(HmacAlgorithms.HMAC_SHA_256, apikey.getBytes(StandardCharsets.UTF_8))).hmacHex(message.getBytes(StandardCharsets.UTF_8));
    }

3. HTTP Status Codes

All based on code.

code	Description	Detailed Explanation
200	ok	success!

4. Common Parameters

Parameter Name	Type	Required	Remarks
accessToken	String	Yes	Signed token string
tenantId	int	Yes	Company id
timestamp	Long	Yes	Millisecond timestamp

5. Common Questions

• Retry times when notification fails

  Explanation: After sending the notification synchronously, any lack of response or any status code that is not 200 is considered a failure. After more than 5 retries, the configuration for that type of WebHook will be disabled.

• How to handle when the configuration is turned off

  Explanation: After turning off the configuration, data collection still happens, but synchronization does not. After turning it on, the system checks once every 10 minutes. Once it detects that it is turned on again, it synchronizes all historical data.

• Timezone

  UTC+8

WebHook Related APIs

📢 The webhook APIs involved in this documentation can be configured separately by contacting customer support or the administrator, or you can configure them yourself using the following APIs.

Query WebHook Configuration

• URI

  /wscrm-bus-api/open/webhook/getConfList

• Request Method

  POST、Content-Type: application/json

• Description

• Request Parameter Description

Parameter Name	Type	Required	Remarks
tenantId	Long	Yes	Company id

• Request Example

{
  "tenantId": 500766
}

• Response Parameter Description

Parameter Name	Type	Remarks
code	int	Response code
message	String	Response message
data	String	Data

• data Parameter Description

Parameter Name	Type	Remarks
type	String	Response code
url	String	Response message
status	int	Status: 0 Normal, 1 Disabled

• Response Example

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "type": "MSG_SYNC_MESSAGE",
      "url": "http::/api.bus.com/syncUserInfo",
      "status": 1
    }
  ]
}

Add (Update) Webhook Configuration

• URI

  /wscrm-bus-api/open/webhook/add

• Request Method

  POST、Content-Type: application/json

• Description

• Request Parameter Description

Parameter Name	Type	Required	Remarks
tenantId	Long	Yes	Company id
info	Object	Yes	Detail data

data Parameter Description

Parameter Name	Type	Required	Remarks
type	String	Yes	Type (see the type table below for details)
url	String	No	API address

• Request Example

{
  "tenantId": 500766,
  "info": {
    "type": "MSG_SYNC_MESSAGE",
    "url": "http://api.bus.com/syncMessage"
  }
}

• Response Parameter Description

Parameter Name	Type	Remarks
code	int	Response code
message	String	Response message
data	String	Response data

• Response Example

{
  "code": 200,
  "message": "Success",
  "data": ""
}

Update WebHook Configuration Status

• URI

  /wscrm-bus-api/open/webhook/updateConfigStatus

• Request Method

  POST、Content-Type: application/json

• Description

• Request Parameter Description

Parameter Name	Type	Required	Remarks
tenantId	Long	Yes	Company id
info	Object	Yes	Detail data

info Parameter Description

Parameter Name	Type	Required	Remarks
type	String	Yes	Type
status	String	Yes	Status: 0 Normal, 1 Disabled

• Request Example

{
  "tenantId": 500766,
  "info": {
    "type": "MSG_SYNC_MESSAGE",
    "url": "http://api.bus.com/syncUserInfo"
  }
}

• Response Parameter Description

Parameter Name	Type	Remarks
code	int	Response code
message	String	Response message
data	String	Response data

• Response Example

{
  "code": 200,
  "message": "Success",
  "data": ""
}

WebHook Configuration Type List

In the documentation, when the API is marked as the webhook type, and <configuration Id> is one of the values in the following list, you can manage it using the API.

type	Description
USER_SYNC_PORTRAIT	User portrait modification sync
MSG_SYNC_MESSAGE	Send/receive messages
USER_WRITE_FLOW	Writing follow-up
GROUP_IN_OR_OUT_GROUP	Group join/leave actions
GS_SYNC_TASK_STATUS	Mass dispatch status sync
GS_V3_REPLY_MESSAGE	Mass dispatch reply message sync
GS_V3_SYNC_TASK_STATUS	Mass dispatch task status sync
GS_V3_SYNC_TASK_DETAIL_STATUS	Mass dispatch task detail status sync
WA_SYNC_ON_OR_OFF_LINE_STATUS	WhatsApp customer service account online/offline status sync
CHANNEL_SYNC_STATUS	channel customer service account status sync
CHANNEL_REGISTER_STATUS	channel registration status sync
CLIENT_SYNC_MESSAGE	Client message sync
CLIENT_SYNC_MESSAGE_STATUS	Client message status sync