Webhook Events

Convotic normalizes webhook payloads from all platforms into a unified event format. This page lists all event types and the standard event envelope.

Event envelope

Every event follows this structure:

{
  "id": "evt_01HQ3X7K9P2M5N8R4T6V",
  "type": "messaging.message.received",
  "workspace_id": "ws_abc123",
  "block_id": "blk_instagram_456",
  "platform": "instagram",
  "timestamp": "2026-03-31T10:15:30.000Z",
  "data": {
    "contact_id": "ct_xyz789",
    "conversation_id": "conv_def012",
    "message": {
      "id": "msg_ghi345",
      "text": "Hi, I want to check my order status",
      "type": "text",
      "direction": "inbound"
    }
  },
  "metadata": {
    "raw_platform_event_id": "mid.$cAAJsujCd0OR1"
  }
}

Envelope fields

Field	Type	Description
id	string	Unique event ID.
type	string	Event type in domain.entity.action format.
workspace_id	string	The workspace this event belongs to.
block_id	string	The Block that produced this event.
platform	string	The source platform (instagram, line, messenger, whatsapp, telegram).
timestamp	string	ISO 8601 timestamp of when the event occurred.
data	object	Event-specific payload (varies by event type).
metadata	object	Additional context, including the raw platform event ID.

Event types by domain

Messaging

Event type	Description
messaging.message.received	An inbound message was received from a contact.
messaging.message.sent	An outbound message was sent to a contact.
messaging.message.delivered	A sent message was delivered to the contact's device.
messaging.message.read	A sent message was read by the contact.
messaging.message.failed	A message failed to send.
messaging.conversation.created	A new conversation was started.
messaging.conversation.closed	A conversation was closed by an agent.
messaging.comment.created	A comment was posted on a social media post.
messaging.story_reply.received	A story reply was received (Instagram).
messaging.reaction.added	A reaction was added to a message.
messaging.reaction.removed	A reaction was removed from a message.
messaging.follow	A user followed / added the account.
messaging.unfollow	A user unfollowed / removed the account.
messaging.postback	A user tapped a postback button.

Commerce

Event type	Description
commerce.order.created	A new order was placed.
commerce.order.updated	An order status was updated.
commerce.order.fulfilled	An order was fulfilled / shipped.
commerce.order.cancelled	An order was cancelled.
commerce.cart.abandoned	A cart was abandoned (no purchase within threshold).

CRM

Event type	Description
crm.contact.created	A new contact was created.
crm.contact.updated	A contact record was updated.
crm.contact.merged	Two contact records were merged.
crm.deal.created	A new deal was created.
crm.deal.stage_changed	A deal moved to a different pipeline stage.

Automation

Event type	Description
automation.workflow.started	A Workflow execution started.
automation.workflow.completed	A Workflow execution completed.
automation.workflow.failed	A Workflow execution failed.
automation.workflow.paused	A Workflow execution is waiting (e.g., Wait for Reply).

Platform

Event type	Description
platform.block.connected	A Block was connected to the workspace.
platform.block.disconnected	A Block was disconnected.
platform.block.error	A Block encountered an error (e.g., expired token).
platform.webhook.verified	A webhook endpoint was verified by a platform.

PTM (Post-Transaction Messaging)

Event type	Description
ptm.notification.sent	A post-transaction notification was sent.
ptm.notification.delivered	A post-transaction notification was delivered.
ptm.notification.clicked	A post-transaction notification link was clicked.