SocialMate Local API

Trigger node & events

Start a workflow on incoming WhatsApp events — the self-registering trigger, signature verification, and all 35 events.

Drop a SocialMate Trigger at the start of a workflow, tick the events you care about, and activate it. The node registers its own webhook on the server when the workflow goes live and removes it when you deactivate — no manual endpoint, no secret to copy. It covers the full 35-event catalogue (9 on Free), and every delivery is HMAC-signed.

Trigger settings

Setting	What it does
Events	One or more of the 35 events below. The workflow fires once per matching delivery.
Verify signature	On by default. Validates the HMAC-SHA256 signature on every delivery and rejects anything unsigned or tampered. Registering the signing secret needs an `admin`-scope key. The node does this for you; if you ever verify by hand, the contract is `X-SocialMate-Signature: sha256=<hex>` over `${timestamp}.${body}` (with the `X-SocialMate-Timestamp` header) — see Webhooks.
Filter by account	Optional — narrow an All accounts key down to a single account on top of the key's own scope.

Self-registration needs admin scope. The trigger creates and deletes its webhook for you, which is an admin action. If your key is read/send only, the node can't register — create the connection in API & Integrations → n8n, which mints an admin-capable key and the signing secret together.

The event envelope

Every delivery shares one envelope: version, event, timestamp, tunnelUrl, and an event-specific data object.

event message.received Free

{
  "version": 1,
  "event": "message.received",
  "timestamp": "2026-06-27T12:00:00.000Z",
  "tunnelUrl": "https://your-name.example.com",
  "data": {
    "accountId": "acc_123",
    "messageId": "ABCD1234",
    "chatId": "15551234567",
    "senderId": "15551234567",
    "body": "Is my order shipped?",
    "type": "text",
    "timestamp": 1750000000000,
    "fromMe": false
  }
}

Reference {{ $json.data.chatId }} and {{ $json.data.body }} downstream. To build an AI reply, feed the chat ID into Message → Get AI Context.

Event catalogue

9 events are available on every tier; the other 26 require Pro. Full payload shapes live in the shared webhook events reference.

Available on Free 9

message.received — an inbound WhatsApp message
message.sent — an outbound message went out
account.connected — an account came online / linked
account.disconnected — an account went offline / unlinked
tunnel.url_changed — the tunnel URL changed (e.g. after restart)
tunnel.stopped — the tunnel disconnected
license.activated — a Pro license activated
license.deactivated — the license was deactivated / downgraded
license.tier_changed — the tier changed (Free ↔ Pro)

Pro events 26

message.delivered — a message you sent reached the recipient's phone (two grey ticks)
message.read — the recipient opened it (two blue ticks) — only when that contact has read receipts on
message.reaction — someone reacted to a message
poll.vote — someone voted on a poll you sent
group.participants_updated — someone joined, left, was promoted or demoted
media.context_updated — your AI agent cached a description/transcript for a media item (Agent Memory)
account.banned — WhatsApp ban detected
contacts.updated — the contact list changed
account.danger_mode_enabled — High-Volume Mode turned on
account.danger_mode_disabled — High-Volume Mode turned off
tunnel.started — a tunnel session started
sync.started · sync.completed · sync.failed — sync lifecycle
media.discovered · media.downloaded · media.failed · media.deleted — media lifecycle
queue.item.enqueued · queue.item.processing · queue.item.sent · queue.item.failed · queue.item.cancelled — per-item queue events
queue.batch.created · queue.batch.completed · queue.batch.cancelled — batch lifecycle

"High-Volume Mode" is the customer-facing name; the wire event names keep their stable account.danger_mode_* identifiers so existing integrations don't break.

Pro keeps the trigger URL stable. A Named tunnel means the webhook endpoint doesn't change across restarts, so your active workflow keeps receiving events without re-registration — and unlocks the 26 Pro events above. Set up a Named tunnel →