Notify


Data can be sent from Hull to external services either through streaming Update Notifications to Connectors or through one-off Exports and “replays” of previous updates (excluding Events) with the Export API.

Hull creates Update Notifications to sync with external services whenever a diff is detected. Notifications are queued and sent to listening Connectors that use them to propagate the new information or change to the 3rd party services they integrate with.

Hull notifications and data export

Building User and Account Update Notifications

User and Account Update Notifications are used to propagate changes to the outside world. Connectors subscribe to those notifications and use this information to synchronise, notify, transform or to apply whatever side effect they are meant to apply.

User Update Notifications are triggered and sent when:

  • A User’s Attributes change
  • A new User Event is ingested
  • A User enters or leaves a User Segment

Account Update Notifications are triggered and sent when:

  • An Account’s Attributes change
  • An Account enters or leaves an Account Segment

Format of a User Update Notification

User Update Notifications are built with the following sections:

  • user contains the latest known version of the user’s User Report (without embedded the AccountReport)
  • account contains, if the User is linked to an Account, the latest known version of that Account Report
  • segments contains the list of Users Segments the User belongs to
  • account_segments contains the list of Accounts Segments the Account belongs to
  • changes captures a diff of the information that changed between the current and previous notification built for that User (description of the changes below)
  • events contains the list of Events associated to the user since the last Notification

Here’s an example payload of a User Update Notification:

{
  "user": {
    "id": "5a7b32a5d57fdbde8f000007",    
    "accepts_marketing": false,
    "created_at": "2018-02-07T17:08:53Z",
    "indexed_at": "2018-02-12T10:17:24+01:00",    
    "domain": "hull.io",
    "email": "stephane@hull.io",
    "external_id": "1",
    "has_password": false,
    "is_approved": false,
    "segment_ids": ["5a815a3fd57fdbb78a000004"],
    "traits_hello": "world"
  },
  "segments": [{
    "id": "5a815a3fd57fdbb78a000004",
    "name": "Users with Email",
    "type": "users_segment",
    "created_at": "2018-02-12T09:11:42Z",
    "updated_at": "2018-02-12T09:16:33Z"
  }],
  "account": {
    "id": "5a7b32a5d57fdbde8f000005",    
    "created_at": "2018-02-07T17:08:53Z",
    "updated_at": "2018-02-07T17:08:53Z",
    "external_id": "account-1",
    "domain" : "hull.io",
    "name" : "Hull inc"
  },
  "account_segments": [{
    "id": "5a815a3fd56fceb79a000001",
    "name": "Accounts with Domain",
    "type": "accounts_segment",
    "created_at": "2018-02-12T09:11:42Z",
    "updated_at": "2018-02-12T09:16:33Z"
  }],
  "events": [
    {
      "properties": { "foo" : "bar" },
      "event_id": "5ad078db8463ba4a550002dd",
      "user_id": "561fba41450f34efa5000019",
      "event_source": "track",
      "app_name": "Shopify",
      "event": "page",
      "event_type": "track",
      "context": {
        "browser": {
          "name": "Safari",
          "version": "11.0.3",
          "major": 11
        },
        "campaign": {
          "name": null,
          "source": null,
          "medium": null,
          "term": null,
          "content": null
        },
        "device": {
          "name": "Other"
        },
        "ip": "10.52.8.14",
        "os": {
          "name": "Mac OS X",
          "version": "10.13.3"
        },
        "page": {
          "url": "https://example.com/account",
          "host": "example.com",
          "path": "/account"
        },
        "referrer": {
          "url": "https://example.com/",
          "host": "example.com",
          "path": "/",
          "campaign": {
            "name": null,
            "source": null,
            "medium": null,
            "term": null,
            "content": null
          }
        },
        "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/604.5.6 (KHTML, like Gecko) Version/11.0.3 Safari/604.5.6"
      },
      "anonymous_id": "1519364950-b671ca2b-e54a-4700-a39f-e60f280a89a8",
      "created_at": "2018-04-13 09:30:52 UTC",
      "session_id": "1523611741-5f7a0160-fe87-4577-956a-ae3834ccc18e",
      "app_id": "561fb665450f34b1cf00000f"
    }
  ],
  "changes": {
    "user": {
      "accepts_marketing": [true, false],
      "email": [null, "stephane@hull.io"],
      "is_approved": [null, false],
      "traits_hello": [null, "world"]
    },
    "segments": {
      "left" : [{
        "id": "5a815a3fd57fdbb78a000003",
        "name": "Anonymous Users",
        "type": "users_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"
      }],
      "entered": [{
        "id": "5a815a3fd57fdbb78a000004",
        "name": "Users with Email",
        "type": "users_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"
      }]
    },
    "account": {
      "name": ["Hull", "Hull inc"],
      "updated_at": ["2018-01-10T09:00:09Z", "2018-02-12T09:22:37Z"]
    },
    "account_segments": {
      "left": [{
        "id": "5a815a3fd56fceb78a000009",
        "name": "Recently updated accounts",
        "type": "accounts_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"
      }],
      "entered": [{
        "id": "5a815a3fd56fceb79a000001",
        "name": "Accounts with Domain",
        "type": "accounts_segment",
        "created_at": "2018-02-12T09:11:42Z",
        "updated_at": "2018-02-12T09:16:33Z"      
      }]
    },
    "is_new": false
  }
}

Format of an Account Update Notification

Account Update Notifications are built with the following sections :

  • account contains the latest known version of that Account Report
  • account_segments contains the list of Accounts Segments the Account belongs to
  • changes captures a diff of the information that changed between the current and previous notification built for that Account (description of the changes below)

Here’s an example payload of an Account Update Notification:

{
  "account": {
    "id": "59367d6ff3829c7dfd000001",
    "external_id": "123",
    "created_at": "2017-06-06T10:01:39Z",
    "updated_at": "2018-04-18T12:22:34Z",
    "name": "Hull",
    "domain": "hull.io",
    "foo": "BAR",
    "is_customer": true,
    "clearbit/domain": "hull.io",
    "clearbit/geo_city": "Atlanta",
    "clearbit/linkedin_handle": "company/hull-io",
    "clearbit/name": "Hull",
    "clearbit/phone": "+1 617-832-1731",
    "clearbit/site_title": "Hull",
    "clearbit/site_url": "http://hull.io",
    "clearbit/tags": [ "SAAS", "Technology", "B2B", "Information Technology & Services" ],
    "clearbit/time_zone": "America/New_York",
  },
  "account_segments": [
    {
      "id": "5a6f3036bf7d83932600003a",
      "name": "Product Qualified Lead",
      "type": "accounts_segment",
      "created_at": "2018-01-29T14:31:18Z",
      "updated_at": "2018-01-29T14:31:18Z"
    }
  ],
  "changes": {
    "account": {
      "name": [ "Hull.io", "Hull" ]
    },
    "account_segments": {
      "left": [{
        "id": "5a6f3036bf7d83932600002b",
        "name": "Marketing Qualified Lead",
        "type": "accounts_segment",
        "created_at": "2018-01-29T14:31:18Z",
        "updated_at": "2018-01-29T14:31:18Z"
      }],
      "entered": [{
        "id": "5a6f3036bf7d83932600003a",
        "name": "Product Qualified Lead",
        "type": "accounts_segment",
        "created_at": "2018-01-29T14:31:18Z",
        "updated_at": "2018-01-29T14:31:18Z"
      }]    
    },
    "is_new": false
  }
}

Diffing and propagating changes

The changes section of the notification contains the following sections:

  • user which contains the attributes that changed on the User Update since the last Notification, capturing the key, previous and current values
  • account is similar to user but capturing changes on the Account Update since last notification
  • segments contains the list of segments the User entered and left
  • account_segments contains the list of segments the Account entered and left
  • is_new is a boolean which is set to true if the notification is the first one that we receive for the user

The events section contains the list of Events captured for the User since the last Notification was sent for that User.

Updates are grouped in small batches, which means that it you have a few connectors that send new information (update Traits and/or track Events) at the same time, they will end up triggering a single outgoing notification containing the result of those multiple updates.

Internal events

Attributes changed and Segments changed are not included in the outgoing notification payloads. They are considered as “Internal” events. The changes object included on the notifications is the preferred way to keep track and propagate changes to the outside world.

Workspace change notifications

User and Account Update Notifications are used to trigger Segment Update Notifications and Ship Update Notifications.

Format of a Segment Update Notification

When a Users Segment or Accounts Segment is created or updated (saved in. the dashboard), a users_segment:update or accounts_segment:update Notification is sent to all listening connectors. users_segment:delete and accounts_segment:delete are also sent when a Segment is deleted.

This features the:

  • id of the Segment
  • name of the Segment (as seen in the dashboard)
  • type either users_segment or accounts_segment
  • created_at date
  • updated_at date

Here’s an example payload of a Segment Update Notification:

{
  "id": "5a6f3036bf7d83932600003a",
  "name": "Product Qualified Lead",
  "type": "accounts_segment",
  "created_at": "2018-01-29T14:31:18Z",
  "updated_at": "2018-01-29T14:31:18Z"
}

Format of a Ship Update Notification

Ships are a legacy term for Connectors. A ship:update Notification is sent when the Connector settings change.

Here’s an example payload of a Ship Update Notification.

{
  "id": "5abe0899e1948d31bd000002",    
  "created_at": "2018-03-30T09:51:22Z",
  "updated_at": "2018-04-18T12:20:17Z",
  "name": "Testing kraken install",
  "description": null,
  "picture": "https://example.connectors.hullapp.net/picture.png",
  "secret": "xxxxxxxxx",
  "tags": [],
  "manifest_url": "https://example.connectors.hullapp.net/manifest.json",
  "source_url": "https://example.connectors.hullapp.net/",
  "private_settings": {
    "foo": "bar"
  },
  "settings": {},
  "type": "ship",
  "status": { "status": "ok", "messages": [] },
  "manifest": {
    "name": "Example",
    "description": "Example connector",
    "tags": ["batch", "kraken"],
    "private_settings": [{
      "name": "foo",
      "title": "Example setting",
      "type": "string"
    }],
    "subscriptions": [{ "url": "/smart-notifier" }],
    "ui": false,
    "picture": "picture.png",
    "readme": "readme.md"
  }
}

Logs for Outgoing Notifications

Outgoing notifications are logged with the outgoing.{entity}.{status} format. These are visible in the Logs view on the Dashboard, or Logs view within each Connector’s page (for jumping to that Connectors logs only)

Log Type Description
outgoing.user.success User was successfully sent to the service
outgoing.user.error User was not successfully sent to the service
outgoing.user.skip User was skipped by the Connector and not sent to the service
outgoing.account.success Account was successfully sent to the service
outgoing.account.error Account was not successfully sent to the service
outgoing.account.skip Account was skipped by the Connector and not sent to the service
outgoing.event.success Event was successfully sent to the service
outgoing.event.error Event was not successfully sent to the service
outgoing.event.skip Event was skipped by the Connector and not sent to the service

Identities for Outgoing Logs

All logs feature an identifier to associate Users and Accounts with the logs. Learn more about identifiers and identity resolution on Hull. For outgoing notifications these include:

Identifier           Description              
user_id ID on the User
user_external_id External ID from the user
user_email User email
user_anonymous_id
account_id ID on the Account
account_external_id External ID on the Account
account_domain Account domain

Connector logs

All data sent out through Connectors is logged and queryable by:

Connector identifier Description
connector_name Reference name of the connector (ex. salesforce or processor)
connector_id ID of the connector

Export API

You can export User and Account data as flat files through the Export API. This has the same querying capabilities as Segments. Read our Export API documentation.

You can define the list of Traits to send in the exported file through the query builder in the Users or Account tab. Any predicate selected will be included, and the values included in the Export.

Note: Events are not sent through the Export API.

Data from your query can be exported as CSV or JSON. The results can either be sent to:

  • An email address
  • HTTP POST to a receiving endpoint
  • A connector that supports it

“Replaying” data to Connectors

Connectors will only receive data when a User or Account Update Notification is triggered. If you install a new Connector, or update your Connector Settings, you will need to “replay” data. You can do this from the Users or Accounts tab by selecting a Segment, or on individual User and Account pages.

Note: You cannot replay Events.

If you update your Trait settings in your Connector, you will need to resend the Segments to see the correct Users and Accounts in your third party tools.