Skip to main content
v1 Subscribe to pipeline record events to learn about every change to a pipeline record in your workspace and about the result of every stage action. Each event uses the common envelope, and its payload carries the record as it is after the change. Use the pipeline records guide when your system also creates or moves records through the REST API.

Event types

Each change produces one event, except a move into a final stage, which produces two: pipeline_record.stage_changed, then pipeline_record.closed. Both carry the same payload; the eventId of pipeline_record.closed ends in :closed.

Envelope


Payload

Fields without a value are left out of the payload, except record.values, which is always present.

Record values

record.values is a list with one item per attribute that has a value: { "id", "label", "type", "value" }. The id of an attribute never changes, so a renamed attribute keeps its id. Read values by id when you store them. Values recorded before Bridge described the attributes arrive with label and type set to null, after the described ones.

Triggers

Close reasons

reason is present when the move carried a close reason, for example when a record is closed as lost with the reason “Price”. reason.id is the close reason of the pipeline, reason.label its text and reason.note the free text written with it. A move into a final stage can also have no close reason.

Stage action events

The actions of a stage run every time a record enters the stage: when it is created in it, when it moves to it and when it is reopened into it. That includes records created in bulk, so a large import into a stage with actions produces one action event per record and action. The action object of a pipeline_action.* event:
TRANSFER_TO_TEAM is not supported yet. A stage that still holds it produces pipeline_action.failed with ACTION_NOT_SUPPORTED, or pipeline_action.skipped with NO_OPEN_SESSION when the record has no open conversation.

Skip reasons

A skipped action is a normal outcome: the action did not apply to this record, so nothing was changed. skipReason is always a code.

Failure reasons

failureReason is CODE or CODE: detail. Switch on the part before the colon; the detail helps support and its text can change. The code is one of:
  • A code of the stage actions themselves, listed below.
  • The error code of the Bridge domain that refused the action, for example BRIDGE_TASK_0308 when the task could not be created.
  • HTTP_<status>, when that domain answered with no error code, for example HTTP_503.
New codes can be added to both lists. The meaning of an existing code never changes, so treat an unknown code as “did not run” and keep processing.

Delivery and ordering

  • Delivery can be duplicated. Discard repeated events as described in Receive events.
  • pipeline_record.closed is sent after its pipeline_record.stage_changed. When a delivery is retried, only the event that was not delivered is sent again, so pipeline_record.closed can arrive later than its pipeline_record.stage_changed.
  • Events of different records are not ordered. For one record, order its events by timestamp.
  • pipeline_action.* events arrive after the pipeline_record.created, pipeline_record.stage_changed or pipeline_record.reopened that ran the actions.
  • Records that existed before you subscribed appear with their next change.

Example payloads

Record event examples

Stage action event examples