Webhooks Overview

Convotic receives real-time events from connected platforms via webhooks. When a user sends a message on Instagram, follows your LINE account, or triggers any other event, the platform delivers a webhook payload to Convotic, which processes it and routes it to the appropriate Workflow.

Event flow

Platform (Instagram, LINE, etc.)
    ↓  HTTP POST
Convotic Webhook Endpoint (/webhooks/:platform)
    ↓  Verify signature
Message Broker (Google Pub/Sub)
    ↓  Fan out
Worker (processes event, triggers Workflows)
    ↓
Workflow Execution Engine

Step-by-step

1. Platform sends a webhook -- when an event occurs (new message, follow, comment), the platform sends an HTTP POST to Convotic's webhook endpoint.
2. Signature verification -- Convotic verifies the webhook signature using the platform's secret to ensure authenticity. See Webhook Security.
3. Publish to message broker -- the verified event is published to Google Pub/Sub for reliable, at-least-once delivery.
4. Worker processes the event -- a worker consumes the event, normalizes it into Convotic's internal event format, updates the relevant contact and conversation, and checks for matching Workflow triggers.
5. Workflow execution -- if a Workflow trigger matches, a new execution begins.

Webhook endpoints

Each platform has a dedicated webhook endpoint:

Platform	Endpoint
Instagram	https://api.convotic.com/webhooks/instagram
LINE	https://api.convotic.com/webhooks/line
Messenger	https://api.convotic.com/webhooks/messenger
WhatsApp	https://api.convotic.com/webhooks/whatsapp
Telegram	https://api.convotic.com/webhooks/telegram

警告

These endpoints are for platform-to-Convotic communication only. Do not send custom payloads to these URLs. To trigger Workflows programmatically, use the API trigger.

Webhook verification

When you connect a Block, Convotic registers its webhook URL with the platform. Some platforms require a verification handshake before they begin sending events:

Platform	Verification method
Instagram / Messenger	Hub challenge (GET request with hub.verify_token)
LINE	No verification handshake; signature on each POST
WhatsApp	Hub challenge (same as Instagram)
Telegram	No verification handshake; webhook set via Bot API

Reliability

• Webhooks are processed with at-least-once delivery via Pub/Sub.
• If processing fails, the event is retried with exponential backoff.
• Events are stored for 30 days and can be replayed from the dashboard under Settings > Webhooks > Event Log.

Monitoring

View incoming webhook events in the dashboard under Settings > Webhooks. Each event shows:

• Timestamp
• Platform and event type
• Processing status (success, failed, retrying)
• Linked Workflow execution (if applicable)