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 WSAPI events, allowing workflows to start when specific real-time events occur in the WSAPI system. It listens for various event types such as messages, session changes (login/logout), chat updates, calls, user profile changes, contacts, and groups.

Common scenarios where this node is beneficial include:

  • Automating responses or processing when new messages arrive.
  • Tracking user login/logout activity.
  • Monitoring call events like incoming calls or call termination.
  • Reacting to changes in chat settings or user presence.
  • Syncing contact or group information updates.

For example, you could use this node to automatically download media files from incoming messages, send notifications on user status changes, or log call activities for analytics.

Properties

Name Meaning
Event Types Select which event types to listen for. Options include: Logged In, Logged Out, Login Error, 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 Automatically download media files when message events contain media. Only applicable when listening to message events.
Parse Event Data Parse the event data based on event type for easier access to fields. When enabled, the output JSON will have event-specific fields extracted at the top level.
Include Raw Event Include the original webhook payload in the output under the rawEvent field.
Webhook Authentication Enable custom header authentication for incoming webhooks. When enabled, the node expects a specific header with a matching value to accept the webhook request.
Auth Header Name The name of the custom HTTP header used for webhook authentication. Required if webhook authentication is enabled. Default is "X-Webhook-Auth".
Auth Header Value The expected value of the authentication header. Required if webhook authentication is enabled.

Output

The node outputs a single item containing:

  • json: An object with event details including:

    • 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 root object if "Parse Event Data" is enabled.
    • eventData: Raw event data if parsing is disabled.
    • rawEvent: The full original webhook payload if "Include Raw Event" is enabled.
    • For message events with media and auto-download enabled, a media field indicating download metadata and possibly a downloadError if the download failed.

  • binary (optional): If media auto-download is enabled and the event contains media, the binary data of the downloaded media file is included here with appropriate filename and MIME type.

Dependencies

  • Requires an API key credential for WSAPI to download media files when "Auto-Download Media" is enabled.
  • The node expects the WSAPI webhook to POST event data to its configured webhook URL.
  • If webhook authentication is enabled, the external service must send the specified custom header with the correct value.

Troubleshooting

  • Webhook Authentication Failure: If enabled, the node rejects requests missing the expected authentication header or with incorrect values. Ensure the external service sends the correct header and value.
  • Missing Event Data: The node ignores webhook calls that do not contain both eventType and eventData. Verify the webhook payload structure matches expectations.
  • Unsupported Event Type: Events not selected in the "Event Types" property are ignored.
  • Media Download Failures: When auto-downloading media, failures can occur due to invalid credentials, network issues, or missing media IDs. The error is recorded in the output but does not stop workflow execution. Check API credentials and network connectivity.
  • Binary Data Handling: Downstream nodes must support binary data to process downloaded media correctly.

Links and References

Discussion