Voyager can push real-time events to your server via webhooks. Instead of polling for new messages or connection requests, configure a webhook URL and Voyager will POST events as they happen. Payloads are signed with HMAC-SHA256, and Slack-formatted delivery is built in.
Management endpoints return the { success, statusCode, message, data, errors } envelope. The JSON examples below show only the endpoint-specific payload — access res.data.<field> in your client. Webhook deliveries to your server use the raw event shape below, not the envelope.
Note: id is a UUID, and the secret you sent is masked to "***" in every response — Voyager never echoes it back. Save it on your side when you create the webhook.
All webhook payloads follow this structure:
id is a UUID per delivery — useful for idempotency on your sideevent is one of the types in the catalogue abovetenantName is the human-readable tenant labeldata varies by event type; the userId of the LinkedIn account the event belongs to lives inside data (not at the top level)Voyager signs every webhook payload with HMAC-SHA256 using the secret you provided at creation. The signature is in the X-Webhook-Signature header.
Always verify the HMAC signature before processing webhook payloads. Without verification, an attacker could send fake events to your endpoint.
If your webhook URL points to a Slack incoming webhook (hooks.slack.com), Voyager automatically formats payloads as Slack messages with rich formatting — no middleware needed.
For Slack webhooks, you do not need to provide a secret — Slack handles authentication via the webhook URL itself. Voyager detects hooks.slack.com URLs and switches to Slack message format automatically.
For production setups, use two webhooks:
message_received, connection_received, post_liked, post_commented, comment_replied, session_expiredaction_send_completed, action_send_failed, action_connect_completed, action_connect_failed, job_completed, job_failedThis prevents test runs and action confirmations from drowning out real inbound signals.
Send a test payload to verify your endpoint is working:
Check recent delivery attempts and their HTTP status codes:
Voyager’s background PollService checks for new messages, connection requests, and notifications every 5 minutes per tenant. When it detects changes, it fires the corresponding webhook events.
The first poll after a session sync takes a state snapshot without firing events — this prevents a flood of historical events on first connect. Only subsequent polls emit deltas.
If all three poll sections (messages, invitations, notifications) fail simultaneously with session errors, Voyager emits a session_expired event and pauses polling for that user until the next cookie sync.