Overview
This node is a webhook trigger designed to handle events from Zalo Official Account (OA). It listens for various user interactions and system events sent by Zalo OA via HTTP POST requests. The node verifies the authenticity of incoming requests using a MAC signature and filters events based on user-selected event types.
Common scenarios where this node is beneficial include:
- Automating responses or workflows when users follow or unfollow a Zalo OA.
- Processing different types of messages sent by users, such as text, images, files, locations, stickers, or GIFs.
- Tracking user interactions with message buttons or links.
- Receiving all events from Zalo OA for comprehensive monitoring or analytics.
Practical examples:
- Automatically sending a welcome message when a user follows the OA.
- Logging or analyzing user-submitted images or files.
- Triggering a workflow when a user clicks a specific button in a message.
- Filtering out unwanted events to focus only on relevant user actions.
Properties
| Name | Meaning |
|---|---|
| OA Secret Key | The secret key from the Zalo OA management page used to verify the authenticity of incoming events. |
| Các Loại Sự Kiện (Events) | The types of events to receive from Zalo OA. Options include: - Người Dùng Follow OA (User follows OA) - Người Dùng Unfollow OA (User unfollows OA) - Người Dùng Gửi Tin Nhắn Văn Bản (User sends text message) - Người Dùng Gửi Hình Ảnh (User sends image) - Người Dùng Gửi File (User sends file) - Người Dùng Gửi Vị Trí (User sends location) - Người Dùng Gửi Sticker (User sends sticker) - Người Dùng Gửi GIF (User sends GIF) - Người Dùng Nhấp Vào Nút (User clicks button) - Người Dùng Nhấp Vào Liên Kết (User clicks link) - Tất Cả Sự Kiện (All events) |
| Xác Thực Mac (Validate MAC) | Boolean option to enable or disable verification of the MAC signature from Zalo OA to ensure security. |
Output
The node outputs JSON data representing the received event with additional metadata:
event_type: The type of event received (e.g., "follow", "user_send_text").- All original fields from the Zalo OA webhook payload are included.
timestamp: The ISO string timestamp when the event was processed.- In case of errors or ignored events, the output includes an
errorormessagefield describing the issue.
If the event is ignored because it is not among the selected event types, the output indicates this with an "ignored" event_type and a message.
No binary data output is produced by this node.
Example output JSON for a valid event:
{
"event_type": "user_send_text",
"timestamp": "2024-06-01T12:00:00.000Z",
// ... other event-specific fields from Zalo OA webhook payload
}
Example output JSON for an error:
{
"event_type": "error",
"error": "Invalid MAC",
"timestamp": "2024-06-01T12:00:00.000Z"
}
Dependencies
- Requires an API key credential (OA Secret Key) from the Zalo Official Account management page.
- Uses cryptographic functions (HMAC SHA256) to validate webhook signatures.
- Must be configured with a webhook URL accessible by Zalo OA to receive events.
- No external libraries beyond Node.js built-in crypto module and n8n core modules are required.
Troubleshooting
- Missing MAC header: If the webhook request lacks the MAC signature header, the node returns a 401 Unauthorized error. Ensure Zalo OA is correctly configured to send the MAC header.
- Invalid MAC: If the MAC signature does not match the computed HMAC using the provided secret key, the node rejects the request with a 401 error. Verify that the OA Secret Key is correct and matches the one in Zalo OA settings.
- Method not allowed: The node only accepts GET (for verification) and POST (for events) methods. Other HTTP methods will result in a 405 error.
- Event ignored: If the event type is not among the selected ones, the node ignores it but responds with 200 OK. Adjust the event selection if you want to process more event types.
- Make sure the webhook endpoint URL is publicly accessible and correctly set in Zalo OA's webhook configuration.