Webhook
1. Webhook Introduction#
The DM Hub platform provides a variety of Open API for calling external systems, but in some cases, it may be necessary for DM Hub to be able to actively push messages to external systems at an appropriate time, such as various end systems that can push messages to customers when the automated process is executed to a specific step.
The Webhook function is the message push mechanism provided by DM Hub, which can push messages to interfaces registered on the DM Hub platform.
For example, A customer submits an order in Mini Program, and the order contains the main push item A, but it is not paid 20 minutes after submitting the order. At this time, you can send a message to remind the customer to complete the payment, and at the same time, you can push the coupon issuance instruction to Mini Program through Webhook, triggering Mini Program to actively fill the coupon to the customer, resulting in the completion of the transaction. (in this example, the behavior of submitting orders and commodity information of small and medium-sized programs needs to be connected with data through custom events, burial sites, etc. For more information, please see Mini Program).
2.Create Webhook#
Click 【DM Hub】-【Settings Center】-【Webhook】 to enter the Webhook list page, and click the 【New】 button in the upper right corner to create a new Webhook.
2.1 Parameter Description#
Name: Give Webhook a meaningful name to facilitate subsequent review and change.
Message receiving address: The receiving address of the Webhook message. The address must be a legal and complete address, including the protocol used (such as HTTP or HTTPS).
Authentication method: To prevent non-credit subjects from accessing the message receiving address, the provider of the message receiving address needs to provide a certain authentication mechanism. DM Hub supports using the following authentication mechanism to access the message receiving address. For more information, please see Webhook authentication.
Secret key: DM Hub uses the key to sign the message content when sending a message, and the message receiving address verifies the signature when the message is received, to ensure that the message source and the message content have not been tampered with.
Basic authentication: DM Hub uses HTTP basic authentication to access the message receiving address when sending messages.
OAuth2: When DM Hub sends a message, (client credentials) accesses the message receiving address using the client credential method of OAuth2.
None: When DM Hub sending messages, no authentication method is used.
Trigger type
Customization: It can be used as an action component in the workflow, or manually circle the crowd to push messages. To select this trigger type, you need to set the message type and message body.
Event subscription: Specifies that after the event occurs, the contents of the event are sent to the message receiving address. DM Hub supports subscriptions to events such as customer events, membership events, customer attribute changes, customer identity changes, and marketing campaign attribute changes. When subscribing to multiple events, multiple events are sent to the message receiving address one by one, not receiving all at once. For the message format of event subscriptions, see Webhook trigger type description.
Message type: You can choose to send a message in JSON or text format. If the message type is in JSON format, the Content-Type in HTTP header is application/JSON, If it is in text format, Content-Type is text/plain.
Message body: The message content can be customized and content variables can be optionally inserted. The content variables supported by DM Hub are customer attribute, membership attribute, and in-use commodity attribute. The context event attribute is also supported if the Webhook, is triggered by a workflow.
Automatic retry: If the push fails, it will be retried automatically. When automatic retry is enabled, DM Hub will retry up to 3 times: 30 minutes, 60 minutes, and 90 minutes after sending.
3.Webhook authentication#
3.1 Secret key#
When a Webhook sets the secret key, DM Hub will generate the hmac sha256 hex digest signature of the message content with the secret key and carried in the X-Clab-Hmac-Signature of the header when sending a request to the message receiving address.
In the code that receives the message, the hmac sha256 hex digest signature of the received payload is generated using the same secret key and also compared with the signature in the header. If the two are consistent, the signature verification passes, indicating that the message source is reliable and the message content has not been tampered with.
Generate hmac sha256 hex digest signature: jar package used:
Example of generating signature code:
3.2 Basic Certification#
When a Webhook sets the basic authentication, the Authorization request header is added to the HTTP header when DM Hub sends a request to the message address. The sample code is as follows:
3.3 OAuth2#
For a Webhook set the OAuth2 authentication, DM Hub will ask for the address request from token and get the access_token, then send a message to the message receiving address with the access_token parameter.
3.3.1 The method to obtain token is as follows:
3.3.2 When sending a message, the parameter name is access_token, such as:
3.4 No authentication is used#
If Webhook authentication is not set, no authentication will be done, and the address of the accepted message will be accessed directly.
4.Webhook Message Format#
Webhook supports the following types of messages: custom messages, customer events, customer attribute changes, customer identity changes, and membership events. The following is an explanation of the format of all kinds of messages.
4.1 Custom Message#
Custom messages are used in Webhook sent manually，automatically, and when the form is submitted. The format of the message sent by Webhook will be sent in a user-defined format and the variables in it will be replaced.
Example:
Customize the body of the JSON message:
The content of the message received by the Webhook message receiving address:
The JSON message also carries a MESSAGEID, with the message to facilitate the definition of the problem. Customize the body of the TEXT message:
TEXT message content:
Custom messages support variables in addition to those that can be inserted in the interface, such as customer variables, membership variables, etc. Custom messages also support the following variables:
- tenantId: ID of the tenant who sent the message
- CustomerId: Corresponding to customer
- Campaign: Corresponding campaign code
- WebhookId: Corresponding Webhook Id
- BatchId: The batch number sent this time (not necessarily)
The Webhook sent by the workflow can also use the following variables:
- flowId: Workflow ID
- flowVersion: workflow version number
- flowStep: Process ID of the workflow.
4.2 Customer Events#
For a Webhook, that subscribes to a customer event, the DM Hub will send the contents of the event to the message receiving address when the customer event occurs. Webhook can subscribe to system events and custom customer events. When Webhook subscribes to multiple customer events, multiple events are sent to the receiving address in turn instead of sending multiple events at once. The following is taking a click on the WeChat menu event as an example to illustrate the format of the message.
Example:
Event type: Click WeChat menu event keyword: click_menu message content:
Field description:
| Field | Description |
|---|---|
| MESSAGEID | The message ID sent this time, used for debugging |
| topic | The type of message sent this time, and the topic of customer events all are customerEvent |
| data | The message content of webhook |
| data.event | The type of event and the event that occurred. For customer event Webhook messages, all types are created |
| data.object | The content of the customer incident, concerning the customer events |
4.3 Customer Attribute Change#
For Webhook, subscribed to customer attribute changes, DM Hub will send the changed attribute content to the message receiving address when the customer attribute changes. Webhook can subscribe to system events and custom customer events. The following example is a change in the customer's company properties to illustrate the format of the message.
Example:
Message content:
Field description:
| Field | Description |
|---|---|
| MESSAGEID | The message ID sent this time, used for debugging |
| topic | The type of message sent this time, and the topic of customer events all are customer |
| data | The message content of webhook |
| data.event | The type of event and the event that occurred. For customer event Webhook messages, types can be created,updated, deleted |
| data.object | The content of the customer incident, concerning query customers |
4.4 Change of Customer Identity#
For the Webhook, that subscribes to the customer identity change, DM Hub will send the customer content of the event to the message receiving address when the system customer added, changed, deleted.
Example:
Message content:
Field description:
| Field | Description |
|---|---|
| MESSAGEID | The message ID sent this time, used for debugging |
| topic | The type of message sent this time, and the topic of customer events all are customer |
| data | The message content of webhook |
| data.event | The type of event and the event that occurred. For customer event Webhook messages, types can be created,deleted |
| data.object | Customer identity related information |
| data.object.id | Object ID |
| data.object.version | Version ID |
| data.object.type | Customer source type |
| data.object.value | Changed value |
| data.object.name | Name |
| data.object.tenant_id | tenantId |
| data.object.date_created | Created time |
| data.object.last_updated | Updated time |
| data.object.customer_id | CustomerID |
| data.object.value_md5 | value_md5 |
4.5 Member Events#
For the Webhook, that subscribes to the member event, DM Hub will send the content of the event to the message receiving address when the member event occurs. Webhook currently supports the following five member-related events.
Example:
Event Type: Membership level upgrade event
Event keyword: loyalty/membership_level_up
Message content:
Field description:
| Field | Description |
|---|---|
| MESSAGEID | The message ID sent this time, used for debugging |
| customerId | Customer ID |
| tenantId | tenantId |
| event | keywords of events |
| membershipId | membership ID |
| date | The date what the event occurred |
| oldLevelId | Original level ID |
| newLevelId | New level ID |
| oldLevel | Original level name |
| newLevel | New level name |
Event Type: Membership demotion event
Event keyword: loyalty/membership_level_down
Message content:
Field description:
| Field | Description |
|---|---|
| MESSAGEID | The message ID sent this time, used for debugging |
| customerId | Customer ID |
| tenantId | tenantId |
| event | keywords of events |
| membershipId | membership ID |
| date | The date what the event occurred |
| oldLevelId | Original level ID |
| newLevelId | New level ID |
| oldLevel | Original level name |
| newLevel | New level name |
Event type: System issues coupons
Event keyword: loyalty/loyalty_dispatch_coupon
Message content:
Field description:
| Field | Description |
|---|---|
| tenantId | tenantId |
| event | Keywords of events |
| membershipId | Membership ID |
| date | The date what the event occurred |
| couponId | Coupon ID |
| couponName | Coupon Name |
| batchId | Batch ID |
| couponCode | Coupon code（ The only code of the customer） |
| startDate | Effective date from |
| endDate | Expiration date |
Event type: Get coupon
Event keyword: loyalty/membership_draw_coupon
Message content:
Field description:
| Field | Description |
|---|---|
| tenantId | tenantId |
| event | Keywords of events |
| membershipId | Membership ID |
| date | The date what the event occurred |
| couponId | Coupon ID |
| couponName | Coupon Name |
| batchId | Batch ID |
| couponCode | Coupon code（ The only code of the customer） |
| startDate | Effective date from |
| endDate | Expiration date |
Event type: Write-off coupon event
Event keyword: loyalty/membership_redeem_coupon
Message content:
Field description:
| Field | Description |
|---|---|
| tenantId | tenantId |
| event | Keywords of events |
| membershipId | Membership ID |
| date | The date what the event occurred |
| couponId | Coupon ID |
| couponName | Coupon Name |
| batchId | Batch ID |
| couponCode | Coupon code（ The only code of the customer） |
5. Message Sending#
5.1 Test Send#
Before sending Webhook for a group, you can select a user to send a single message for testing
Test steps:
- Select the Webhook that you want to send in the Webhook list and click the send message button.
- Select Test send.
- Enter the customer name, WeChat nickname, or mobile number in the input box.
5.2 Send in groups#
After the Webhook is created, if the trigger type of the Webhook is a custom trigger, you need to send it manually.
Send steps:
- Select the Webhook that you want to send in the Webhook list and click the send message button.
- Select Group send in the drop-down list sent to the group, select the group to select the send time. If you choose to send at a fixed time, the system starts sending Webhook messages at the specified time.
5.3 View the results of mass posting#
You can view the results sent by webhook in the webhook list.
If it is a test message, you can view the details of the message, including the message body, message header, and the response result of the server. If it is a mass webhook message, you can see the sending status of the message on the sending list page: sending, completed, etc.
5.4 Receive workflow message#
As shown in the following image, when creating a workflow, a Webhook action node can be added to push relevant context information to an external system through Webhook.
5.5 Receive form submission related messages#
As shown in the following image, in the form, you can set the Webhook to be triggered after the form is submitted to push the relevant context information to the external system through Webhook.
5.6 Send Record#
After sending the webhook to the customer, the system records the "system sends Webhook message" event in the customer timeline, and records the Webhook ID and Webhook names in the event attributes.
