Overview
This node acts as a webhook trigger for Zalo Official Account (OA) events. It listens to various types of events sent by Zalo OA via HTTP POST requests and triggers workflows in n8n accordingly. The node verifies the authenticity of incoming webhook requests using a MAC signature to ensure security.
Common scenarios where this node is beneficial include:
- Automating responses or actions when users follow or unfollow a Zalo OA.
- Processing user messages such as text, images, files, locations, stickers, or GIFs sent to the OA.
- Tracking user interactions with buttons or links within messages.
- Filtering and handling only specific event types from Zalo OA.
Practical examples:
- Automatically sending a welcome message when a user follows the OA.
- Logging or analyzing user messages for customer support.
- Triggering marketing campaigns based on user clicks on buttons or links.
- Ignoring irrelevant events to reduce workflow executions.
Properties
| Name | Meaning |
|---|---|
| OA Secret Key | The secret key obtained from the Zalo OA management page, used to verify webhook request signatures. |
| Các Loại Sự Kiện | The types of events to receive from Zalo OA. Options include: - Người Dùng Follow OA (follow) - Người Dùng Unfollow OA (unfollow) - Người Dùng Gửi Tin Nhắn Văn Bản (user_send_text) - Người Dùng Gửi Hình Ảnh (user_send_image) - Người Dùng Gửi File (user_send_file) - Người Dùng Gửi Vị Trí (user_send_location) - Người Dùng Gửi Sticker (user_send_sticker) - Người Dùng Gửi GIF (user_send_gif) - Người Dùng Nhấp Vào Nút (user_click_button) - Người Dùng Nhấp Vào Liên Kết (user_click_link) - Tất Cả Sự Kiện (all) |
| Xác Thực Mac | Boolean flag to enable or disable verification of the MAC signature from Zalo OA for security. |
Output
The node outputs JSON data representing the received webhook event from Zalo OA. The output JSON includes:
event_type: The type of event received (e.g., "follow", "user_send_text").- All original event data fields sent by Zalo OA.
- A
timestampfield indicating when the event was processed by the node.
If an event is ignored because it is not among the selected event types, the output will contain an event with:
event_type: "ignored"original_event: The actual event type received.message: Notification that the event was ignored.timestamp: Processing time.
In case of errors (e.g., missing or invalid MAC), the output JSON contains:
event_type: "error"error: Description of the error.timestamp: Processing time.
The node does not output binary data.
Dependencies
- Requires an API key credential (OA Secret Key) from Zalo Official Account for MAC signature verification.
- Uses Node.js crypto module internally to compute HMAC SHA256 signatures.
- Must be configured with a valid webhook URL registered in Zalo OA settings to receive events.
- No additional external services are required beyond Zalo OA and n8n environment.
Troubleshooting
- Missing MAC header: If the MAC signature header is missing in the webhook request while MAC validation is enabled, the node returns a 401 Unauthorized error. Ensure Zalo OA sends the MAC header and the node's MAC validation property is enabled.
- Invalid MAC: If the computed MAC signature does not match the header, the node rejects the request with a 401 error. Verify that the OA Secret Key is correct and matches the one configured in Zalo OA.
- Event ignored: If the event type received is not among the selected event types, the node ignores it and returns a 200 OK with a message. Adjust the selected event types if you want to process more events.
- Method not allowed: The node only accepts GET (for webhook verification) and POST (for event delivery). Other HTTP methods will result in a 405 error.
- Webhook verification failure: On GET requests, the node responds with the challenge token to verify the webhook. If this fails, check your webhook URL configuration in Zalo OA.