WSAPI Trigger icon

WSAPI Trigger

Trigger on WSAPI webhook events (messages, chats, calls, users, etc.)
Join our community

Actions7

Overview

This node acts as a webhook trigger for WSAPI events, allowing workflows to respond to various real-time events such as messages, session changes, chat updates, calls, user profile changes, contacts, and groups. It listens for incoming webhook POST requests containing event data and triggers the workflow when specified event types occur.

Common scenarios where this node is beneficial include:

  • Automating responses or processing when new messages arrive.
  • Tracking user login/logout events for auditing or notifications.
  • Monitoring call events to log or react to incoming/outgoing calls.
  • Syncing contact or group information updates with other systems.
  • Downloading media files automatically when media messages are received.

Practical example:

  • A customer support workflow that triggers whenever a new message arrives, automatically downloads any attached media, parses the message content, and routes it to the appropriate team member.

Properties

Name Meaning
Event Types Select which event types to listen for. Options include: Logged In, Logged Out, Login Error, Message (new message), Message Read, Message Deleted, Message Starred, Message History Sync, Chat Setting, Chat Presence, Call Offer, Call Accept, Call Terminate, User Push Name, User Status, User Picture, User Presence, Contact, Group. Default is "Message".
Auto-Download Media Boolean option to automatically download media files when message events contain media. Only applicable if listening to message events.
Parse Event Data Boolean option to parse the eventData field based on event type for easier access to individual fields. Defaults to true.
Include Raw Event Boolean option to include the original webhook payload in the output under rawEvent. Defaults to false.
Webhook Authentication Enable custom header authentication for incoming webhooks. If enabled, requires specifying the header name and expected value.
Auth Header Name The custom HTTP header name used for webhook authentication. Required if webhook authentication is enabled. Defaults to "X-Webhook-Auth".
Auth Header Value The expected value of the authentication header. Required if webhook authentication is enabled.

Output

The node outputs JSON data representing the event received from the WSAPI webhook. The structure includes:

  • instanceId: Identifier of the WSAPI instance.
  • receivedAt: Timestamp when the event was received.
  • eventType: The type of event triggered.
  • Parsed event data fields merged into the output object if parsing is enabled.
  • Optionally, the raw webhook payload under rawEvent if requested.
  • For message events with media and auto-download enabled, binary data of the downloaded media file is included in the output under a binary property.

If media is downloaded, additional metadata such as download timestamp and auto-download flag are added to the media info. If downloading fails, an error message is included instead.

Dependencies

  • Requires an API key credential for WSAPI to download media files when auto-download is enabled.
  • Needs proper configuration of the webhook URL in WSAPI to send events to this node.
  • Optional webhook authentication via custom HTTP headers can be configured for security.

Troubleshooting

  • No webhook response / no trigger firing: Ensure the WSAPI service is correctly sending events to the webhook URL exposed by this node. Verify selected event types match those sent by WSAPI.
  • Authentication failures: If webhook authentication is enabled, confirm the header name and value match exactly what WSAPI sends.
  • Media download errors: When auto-download is enabled, failures may occur due to invalid credentials, network issues, or missing media IDs. Check API key validity and network connectivity.
  • Parsing issues: If event data parsing is disabled, users must handle raw event data manually downstream.
  • Binary data handling: Downstream nodes must support binary data to process downloaded media files properly.

Links and References

  • WSAPI official documentation (for event types and webhook setup)
  • n8n documentation on webhook triggers and binary data handling
  • General best practices for securing webhooks with custom headers

Discussion