Skip to content

Webhook Event Topics & Payloads

This page details all available webhook event topics and their payload structures.

1. Available Topics

Topic Channel Trigger Condition
message.sent Viber, SMS Dispatched when the message is successfully handed off to the carrier or messaging provider.
message.delivered Viber, SMS Dispatched when the destination network confirms delivery to the recipient's handset.
message.seen Viber Dispatched when the recipient opens and reads the Viber message.
message.clicked Viber, SMS Dispatched when the recipient clicks a link or CTA button inside the message. Includes click device telemetry.
message.failed Viber, SMS Dispatched when delivery fails permanently (e.g. invalid handset, subscriber unavailable, carrier block).
message.expired Viber Dispatched when a Viber message reaches its TTL expiration without successful delivery.

2. Message Event Payload Schema

Every webhook event is delivered as a JSON object with the following structure:

Field Type Description
campaign_id String The secure public ID of the campaign under which this message was sent.
channel String Messaging channel ("viber" or "sms").
message_id String Unique UUID v7 identifier for the message.
topic String The specific event topic (e.g. "message.delivered", "message.clicked").
timestamp Integer Unix timestamp in seconds when the event occurred.
status String Message status ("sent", "delivered", "seen", "clicked", "failed", "expired").
metadata Object Event-specific metadata (contains device and referrer details for message.clicked).
client_reference String / Null The client reference provided during initial dispatch.
error Object / Null Error details if the status is "failed".

3. Example Webhook Payloads

Event message.delivered

{
  "campaign_id": "cmp_01J8K92M4",
  "channel": "viber",
  "message_id": "0191636f-bcf0-7813-9f89-8d7681728271",
  "topic": "message.delivered",
  "timestamp": 1724164200,
  "status": "delivered",
  "metadata": {},
  "client_reference": "order_checkout_98142",
  "error": null
}

Event message.clicked (with Click Metadata)

For message.clicked events, the metadata object contains device and browser telemetry:

{
  "campaign_id": "cmp_01J8K92M4",
  "channel": "viber",
  "message_id": "0191636f-bcf0-7813-9f89-8d7681728271",
  "topic": "message.clicked",
  "timestamp": 1724164320,
  "status": "clicked",
  "metadata": {
    "device_os": "iOS",
    "device_type": "mobile",
    "browser": "Safari",
    "country": "GR",
    "referer": "https://viber.com"
  },
  "client_reference": "order_checkout_98142",
  "error": null
}

Event message.failed

{
  "campaign_id": "cmp_01J8K92M4",
  "channel": "sms",
  "message_id": "0191636f-bcf0-7813-9f89-8d7681728271",
  "topic": "message.failed",
  "timestamp": 1724164205,
  "status": "failed",
  "metadata": {},
  "client_reference": "order_checkout_98142",
  "error": {
    "code": 1009,
    "message": "Not a Viber User"
  }
}