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.
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:
Account Update Notifications are triggered and sent when:
User Update Notifications are built with the following sections:
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
}
}
Account Update Notifications are built with the following sections :
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
}
}
The changes
section of the notification contains the following sections:
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 Attributes and/or track Events) at the same time, they will end up triggering a single outgoing notification containing the result of those multiple updates.
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.
User and Account Update Notifications are used to trigger Segment Update Notifications and Ship Update Notifications.
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:
users_segment
or accounts_segment
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"
}
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"
}
}
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 |
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 |
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 |
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 Attributes 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:
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 Attribute settings in your Connector, you will need to resend the Segments to see the correct Users and Accounts in your third party tools.