SubizDeveloper Docs
Webhooks

Webhook · Not tied to an API route version

Event payload examples

Read message, customer, and conversation events in a webhook delivery.

Verify the request signature before reading these fields. Each request wraps one or more events in an events array.

The examples below are shortened payloads with synthetic values. They show supported fields, not an exhaustive event catalog or a guarantee that optional fields are always present.

Choose the event type

Event Data object Use it to
message_sent data.message Receive messages and associate them with a conversation.
user_created data.user Create or link a customer record in your CRM.
user_info_updated data.user Synchronize customer information.
conversation_assigned data.conversation Update the responsible agent.
conversation_unassigned data.conversation Clear the responsible agent.

Select the first three types under Custom event when creating a webhook. Assignment events are supported by the backend but are not listed in the current creation form; the assignment examples apply only to subscriptions already configured for those types.

Read the event envelope

Field Meaning
id Event ID. Combine with account_id to deduplicate processing.
account_id Subiz account that the event belongs to.
type Event name. Use it to choose how to read data.
created Time the event was recorded in Subiz, as Unix milliseconds.
event_time Original occurrence time, when provided, in Unix milliseconds. Fall back to created if absent.
by Actor context, when available. by.type identifies the actor type; by.id identifies the actor.
data Data for this event type.

These paths are relative to each item in events, for example events[0].id. Do not confuse the event ID with a user ID, conversation ID, or the X-Subiz-Delivery header.

Fields with empty values can be omitted. by may be absent or contain only context such as device information. Validate what your handler needs and tolerate additional fields.

Message sent

A message_sent event can represent a customer message, an agent reply, or automated content. It does not by itself confirm delivery to an external channel.

{
  "events": [
    {
      "id": "event_example_1",
      "account_id": "account_example",
      "created": 1794614400000,
      "type": "message_sent",
      "by": {
        "id": "user_example",
        "type": "user"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "plaintext",
          "text": "Can you help with my order?"
        }
      }
    }
  ]
}

Use data.message.conversation_id to associate the message with a conversation. Check by.type to distinguish a customer (user) from an agent (agent), and check data.message.is_internal before treating a message as customer-facing. Do not automatically reply to every message_sent event: your own replies can trigger the same event type.

Rich message blocks

When format is block, read data.message.block as a tree. content contains child nodes; text nodes can include formatting such as bold.

{
  "events": [
    {
      "id": "event_example_2",
      "account_id": "account_example",
      "created": 1794614401000,
      "type": "message_sent",
      "by": {
        "id": "agent_example",
        "type": "agent"
      },
      "data": {
        "message": {
          "conversation_id": "conversation_example",
          "format": "block",
          "text": "Hello Alex",
          "block": {
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "Hello "
              },
              {
                "type": "text",
                "text": "Alex",
                "bold": true
              }
            ]
          }
        }
      }
    }
  ]
}

This renders “Hello Alex”. Keep the block tree when storing rich content; text alone loses formatting. Messages can also contain attachments, and a message without text is not necessarily empty. See Rich messages with blocks.

Customer created

user_created contains the customer in data.user. Use (account_id, data.user.id) as your CRM’s Subiz reference. Customers are users, not staff agents.

{
  "events": [
    {
      "id": "event_example_3",
      "account_id": "account_example",
      "created": 1794614399000,
      "type": "user_created",
      "data": {
        "user": {
          "id": "user_example",
          "account_id": "account_example",
          "attributes": [
            {
              "key": "fullname",
              "text": "Alex Example"
            },
            {
              "key": "created",
              "datetime": "2026-11-13T23:59:59Z"
            }
          ]
        }
      }
    }
  ]
}

attributes is an array, not an object keyed by name. Find the attribute whose key is fullname, then read text. Date attributes use datetime; other attributes can use number or boolean. Do not use array position to identify a field.

Customer information updated

user_info_updated carries customer information under data.user. Treat it as a synchronization update, not a list containing only changed fields.

{
  "events": [
    {
      "id": "event_example_4",
      "account_id": "account_example",
      "created": 1794614402000,
      "type": "user_info_updated",
      "data": {
        "user": {
          "id": "user_example",
          "account_id": "account_example",
          "attributes": [
            {
              "key": "fullname",
              "text": "Alex Example",
              "modified": 1794614402000,
              "by_type": "agent",
              "by": "agent_example"
            },
            {
              "key": "created",
              "datetime": "2026-11-13T23:59:59Z"
            }
          ]
        }
      }
    }
  ]
}

Here, modified records an attribute’s update time in Unix milliseconds. Its by and by_type describe who updated that attribute; they are separate from the optional event-level by object.

Upsert only the fields your CRM uses. An omitted attribute is not an instruction to delete its CRM value. Rapid updates to the same customer can be combined before webhook delivery, so this event is not a complete audit trail of every edit. Fetch Get customer details when you need the latest record.

Conversation assigned

conversation_assigned carries the conversation ID and responsible agent in data.conversation. This is ownership, not membership or an invitation to join.

{
  "events": [
    {
      "id": "event_example_5",
      "account_id": "account_example",
      "created": 1794614403000,
      "type": "conversation_assigned",
      "data": {
        "conversation": {
          "id": "conversation_example",
          "assignee": "agent_example"
        }
      }
    }
  ]
}

Ownership cleared

conversation_unassigned indicates that ownership was cleared. The empty assignee is omitted in this example. Use the event type to recognize the change; do not treat every missing assignee on other event types as an instruction to clear ownership.

{
  "events": [
    {
      "id": "event_example_6",
      "account_id": "account_example",
      "created": 1794614404000,
      "type": "conversation_unassigned",
      "data": {
        "conversation": {
          "id": "conversation_example"
        }
      }
    }
  ]
}

See Assign an agent for the corresponding conversation operation.

Process a batch safely

For each event, deduplicate by (account_id, id), route by type, and validate the matching data object. A batch can contain several customers or conversations. Ignore unsupported event types safely and do not assume delivery order matches creation order.

Store all accepted work before acknowledging the batch. See Acknowledge and process for the receiver flow.