WebHook

WebHook Integration Specification

Note: To integrate webhook API, please contact customer success personnel (provide the corresponding webhook configuration address and type) for configuration, or configure it yourself through webhook-related interfaces.

1. Interaction Flow

2. Interface Security Specification

Contact administrator to obtain secret key and company id (obtain from SalesEpoch management backend)

• Interface request encryption method-1 (recommended)

This encryption method places encrypted fields in the request header (header).

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

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

• Interface request encryption method-2

This encryption method places encrypted fields in the request body (body) of the interface.

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

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

Note: For integrations after June 2024, all use the first encryption method (passing parameters in request 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 Code

All based on code

code	Description	Detailed Explanation
200	ok	success!

4. Common Parameters

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

5. Common Issues

• Notification failure retry count

  Description: After notification synchronization, non-response or status codes other than 200 are considered failures. More than 5 failures will close the WebHook configuration information of this type.

• How to handle configuration closure

  Description: After closing the configuration, data collection continues but synchronization stops. When the configuration is opened, detection is performed at 10-minute intervals. After detection shows it's open, all historical data will be synchronized.

• Timezone

  UTC+8

WebHook Related Interfaces

📢 The webhook interfaces mentioned in this document can be configured separately by contacting customer service or administrator, or you can use the following interfaces to configure them yourself.

Query Configured WebHook

• URI

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

• Request Method

  POST、Content-Type: application/json

• Description

• Request Parameter Description

Parameter Name	Type	Required	Description
tenantId	Long	Yes	Company id

• Request Example

{
  "tenantId": 500766
}

• Response Parameter Description

Parameter Name	Type	Description
code	int	Response code
message	String	Response info
data	String	Data

• data Parameter Description

Parameter Name	Type	Description
type	String	Response code
url	String	Response info
status	int	Status 0、normal 1、closed

• Response Example

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

Add (Modify) Webhook Configuration

• URI

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

• Request Method

  POST、Content-Type: application/json

• Description

• Request Parameter Description

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

data Parameter Description

Parameter Name	Type	Required	Description
type	String	Yes	Type (refer to the type table below)
url	String	No	Interface address

• Request Example

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

• Response Parameter Description

Parameter Name	Type	Description
code	int	Response code
message	String	Response info
data	String	Response data

• Response Example

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

Modify 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	Description
tenantId	Long	Yes	Company id
info	Object	Yes	Detail data

info Parameter Description

Parameter Name	Type	Required	Description
type	String	Yes	Type
status	String	Yes	Status 0、normal 1、closed

• Request Example

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

• Response Parameter Description

Parameter Name	Type	Description
code	int	Response code
message	String	Response info
data	String	Response data

• Response Example

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

WebHook Configuration Type List

When the interface in the document is marked with webhook type, and the Configuration Id is a value in the list below, you can use the interface for management.

type	Description
USER_SYNC_PORTRAIT	User portrait modification sync
MSG_SYNC_MESSAGE	Send/receive messages
USER_WRITE_FLOW	Write follow-up
GROUP_IN_OR_OUT_GROUP	Join/leave group behavior
GS_SYNC_TASK_STATUS	Group send status sync
GS_V3_REPLY_MESSAGE	Group send message reply sync
GS_V3_SYNC_TASK_STATUS	Group send task status sync
GS_V3_SYNC_TASK_DETAIL_STATUS	Group send task detail status sync
WA_SYNC_ON_OR_OFF_LINE_STATUS	WhatsApp customer service number online/offline status sync
CHANNEL_SYNC_STATUS	channel customer service number status sync
CHANNEL_REGISTER_STATUS	channel registration status sync
CLIENT_SYNC_MESSAGE	Client message sync
CLIENT_SYNC_MESSAGE_STATUS	Client message status sync