WSAPI Trigger icon

WSAPI Trigger

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

Actions7

Overview

This node acts as a trigger for WSAPI webhook events, allowing workflows to respond to various real-time events such as messages, chats, calls, user updates, and more. It listens for incoming webhook POST requests from the WSAPI service and triggers the workflow when specified event types occur.

Common scenarios include:

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

For example, you could use this node to automatically download media files sent in messages, update CRM records when user profiles change, or log call activity for analytics.

Properties

Name Meaning
Parse Event Data Whether to parse the eventData field based on the event type for easier access to its fields (true/false).
Include Raw Event Whether to include the original full 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 webhook requests.

Output

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

  • instanceId: Identifier of the WSAPI instance.
  • receivedAt: Timestamp when the event was received.
  • eventType: Type of the event (e.g., message, call_offer).
  • Parsed event data fields merged directly into the output if parsing is enabled.
  • If parsing is disabled, the raw eventData object is included under the eventData key.
  • Optionally, the original raw webhook payload is included under rawEvent if enabled.
  • For message events containing media, if auto-download is enabled, the media file is downloaded and attached as binary data with metadata including filename and MIME type.
  • Media download status and timestamps are added to the event data when applicable.

If media is auto-downloaded, the binary data is available in the output alongside the JSON.

Dependencies

  • Requires an API key credential to authenticate requests for downloading media files.
  • The node expects the WSAPI service to send webhook POST requests to the configured webhook URL.
  • Optional webhook authentication via custom HTTP headers can be enabled to secure incoming requests.
  • Network access to the WSAPI media download endpoint is required if auto-download media is enabled.

Troubleshooting

  • Webhook Authentication Failure: If enabled, ensure that the incoming webhook request includes the correct custom header with the expected value. Otherwise, the node will ignore the request without triggering.
  • Missing Event Data: The node requires the webhook payload to contain both eventType and eventData. If these are missing, the webhook response is ignored.
  • Unsupported Event Type: Only events matching the selected event types trigger the workflow. Make sure your WSAPI webhook sends events of the types you have configured.
  • Media Download Failures: When auto-downloading media, failures can occur due to invalid credentials, network issues, or missing media IDs. Errors are recorded in the event data but do not stop the workflow.
  • Credential Configuration: Ensure the API key credential for WSAPI is correctly set up with valid base URL, API key, and instance ID for media downloads.

Links and References

  • WSAPI official documentation (for webhook event types and media download API)
  • n8n documentation on creating webhook triggers and handling binary data

Discussion