KiotViet Trigger icon

KiotViet Trigger

Xử lý các sự kiện từ KiotViet thông qua webhook
Join our community

Overview

This node acts as a trigger for events from the KiotViet platform via webhooks. It listens for specific types of updates or deletions related to customers, products, stock, orders, invoices, price books, categories, and branches in KiotViet. When such an event occurs, KiotViet sends a webhook notification to this node, which then processes and outputs the event data.

Common scenarios where this node is beneficial include:

  • Automating workflows when customer information changes.
  • Syncing product or inventory updates with other systems.
  • Triggering actions on order or invoice updates.
  • Monitoring deletions of entities like products or price books to maintain data consistency.
  • Filtering events by branch or status to handle only relevant data.

Practical example: Automatically update your CRM system whenever a customer’s details are updated in KiotViet, or send notifications when an order status changes.

Properties

Name Meaning
Sự Kiện The specific event type to listen for. Options include various update and delete events for customers, products, stock, orders, invoices, price books, price book details, categories, and branches.
Webhook Secret A secret string (at least 8 characters) used to authenticate incoming webhook requests from KiotViet, ensuring that the webhook calls are legitimate.
Mô Tả Webhook A description for the webhook, useful for identifying it within KiotViet's system. Defaults to "Webhook n8n cho KiotViet".
Bộ Lọc Optional filters to narrow down the events received:
- ID Chi Nhánh: Only receive events from a specific branch ID.
- Trạng Thái: Filter events by specific statuses such as Completed, Processing, or Canceled.

Output

The node outputs JSON data representing the webhook event received from KiotViet. The structure varies depending on the event but generally includes:

  • eventType: The type of event triggered (e.g., customer.update, product.delete).
  • webhookId and attemptNumber: Identifiers for the webhook call attempt (if available).
  • data: The main payload data associated with the event (usually under Notifications[0].Data).
  • removedIds: For delete events, an array of IDs that were removed.
  • rawPayload: The full original webhook payload as received.
  • receivedAt: Timestamp when the webhook was processed.
  • signatureValid: Boolean indicating if the webhook signature matched the expected HMAC.
  • webhookUrl: The URL endpoint receiving the webhook.

If the webhook payload contains binary data, it would be included in the data field, but this node primarily handles JSON event data.

Dependencies

  • Requires an API key credential for authenticating with KiotViet’s API to manage webhook registration.
  • Uses KiotViet’s REST API to create, check, and delete webhooks.
  • Requires the user to provide a webhook secret for validating incoming webhook signatures.
  • No additional external services beyond KiotViet’s API are needed.
  • The node expects to be configured with a publicly accessible webhook URL.

Troubleshooting

  • Webhook Secret Too Short: The node requires the webhook secret to be at least 8 characters. If shorter, webhook creation will fail.
  • Invalid Webhook Signature: Incoming webhook requests without the correct HMAC signature header (x-hub-signature) or with mismatched signatures will be ignored to prevent unauthorized triggers.
  • Webhook Creation Failures: Errors during webhook registration with KiotViet’s API may occur due to network issues, invalid credentials, or API limits. Check API credentials and network connectivity.
  • Duplicate Webhooks: The node attempts to remove existing webhooks of the same event type before creating a new one to avoid duplicates. Failure to delete old webhooks might cause unexpected behavior.
  • Invalid Payload Format: If the webhook payload is not valid JSON, the node will throw an error. Ensure KiotViet sends properly formatted JSON payloads.
  • Filtering Issues: Filters on branch ID or status must match the event data; otherwise, no events will be triggered.

Links and References

Discussion