WSAPI Trigger icon

WSAPI Trigger

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

Actions7

Overview

This node acts as a webhook trigger for user-related events from a WebSocket API (WSAPI). It listens for specific user events such as updates to the user's display name, status message, profile picture, or online presence. When one of the selected events occurs, the node triggers and outputs the event data.

Common scenarios where this node is useful include:

  • Automating workflows based on user profile changes, e.g., updating a CRM when a user changes their display name or profile picture.
  • Monitoring user presence status to trigger notifications or update dashboards.
  • Logging or auditing user status updates in real-time.

Practical example: A company wants to track when users update their profile pictures to automatically refresh their avatars in an internal directory. This node can listen for the "User Picture" event and trigger a workflow that downloads the new image and updates the directory.

Properties

Name Meaning
User Events Select which user events to listen for. Options: User Push Name, User Status, User Picture, User Presence.
Parse Event Data Whether to parse the eventData field for easier access to its properties (true/false).
Include Raw Event Whether to include the original webhook payload in the output (true/false).
Webhook Authentication Enable custom header authentication for incoming webhooks (true/false).
Auth Header Name The name of the HTTP header used for webhook authentication (e.g., "X-Webhook-Auth").
Auth Header Value The expected value of the authentication header to validate incoming requests.

Output

The node outputs JSON data representing the triggered event with the following structure:

  • instanceId: Identifier of the WSAPI instance.
  • receivedAt: Timestamp when the event was received.
  • eventType: The type of user event triggered (e.g., "user_push_name").
  • Parsed event data fields merged directly into the output if "Parse Event Data" is enabled.
  • If parsing is disabled, the raw eventData object is included under the eventData key.
  • Optionally, the full raw webhook payload is included under rawEvent if "Include Raw Event" is enabled.
  • For media-type user events (not typical for user events but supported generally), if auto-download is enabled, the node attempts to download the media file and includes it as binary data in the output with metadata such as filename and MIME type.

Dependencies

  • Requires an optional API key credential to authenticate and download media files if "Auto-Download Media" is enabled (though this property is not exposed for the "user" operation specifically).
  • The node expects to receive webhook POST requests at a configured path.
  • If webhook authentication is enabled, the node requires the user to specify a custom HTTP header name and expected value to validate incoming requests.

Troubleshooting

  • No webhook response: If the incoming webhook payload does not contain eventType or eventData, or if the event type is not among the selected ones, the node will ignore the request without triggering.
  • Authentication failures: If webhook authentication is enabled but the incoming request lacks the correct header or value, the node will reject the request silently.
  • Media download errors: If media auto-download is enabled and the node fails to download media (e.g., due to invalid credentials or network issues), the error is recorded in the output under a downloadError field but does not stop the workflow.
  • Missing credentials: To enable media download, valid API credentials must be configured; otherwise, media download will fail.

Links and References

  • n8n Webhook Trigger Documentation
  • WSAPI documentation (specific to the service providing these events) would be needed for detailed event schemas and authentication setup.

Discussion