Contact Attributes Changed Webhook Examples

🚧
Prerequisites

The webhook endpoint URL should be provided by your server instead of YCloud. Make sure to replace the URL with your actual webhook endpoint URL.

Make sure that your webhook endpoint is listening for the appropriate event types. See also Configure Webhooks, Retrieve a webhook endpoint API.

Occurs when a contact's attributes are modified. The webhook payload contains information about what attributes were changed, including their old and new values.

Tags Change Example (Add Tags)

{
  "id": "evt_1234567892",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter"],
        "newValue": ["premium", "newsletter", "vip"],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Tags Change Example (Remove Tags)

{
  "id": "evt_1234567893",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter", "vip"],
        "newValue": ["premium", "newsletter"],
        "extra": [
          {
            "action": "REMOVED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Change Example

{
  "id": "evt_1234567900",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "waba_id": {
        "oldValue": "waba_old_123456",
        "newValue": "waba_new_789012",
        "extra": [
          {
            "action": "CHANGED"
          }
        ]
      }
    }
  }
}

Notes

Correct Structure: The contactAttributesChanged object contains three required fields: id, updateTime, and changedAttributes.
Changed Attributes: The changedAttributes field is an object where each key is the attribute name and the value is a ContactAttributeChange object.
Event Property Configuration: When enabling contact.attributes_changed events, you must configure the eventProperties field in your webhook endpoint to specify which attributes should be included in the webhook payload.
Attribute Types: The oldValue and newValue fields can contain different data types:
- String: text values
- Number: numeric values (integer or decimal)
- Boolean: true/false values
- Array: arrays of strings
- Object: complex objects with nested properties
- Null: when an attribute is removed or unset
Tags Changes: For tag attributes, the extra field provides detailed information about which tags were added or removed, including their IDs and values.
Null Values: When an attribute is removed or set to null, the newValue will be null. When an attribute is newly added, the oldValue may be null.
Custom Attributes: Custom attributes are included in the changedAttributes object just like standard attributes, with their custom keys as the attribute names.
Change Detection: Only attributes that have actually changed are included in the changedAttributes object.
Extra Field: The extra field is optional and is primarily used for tag-related changes to provide additional context about the specific actions performed.