Table of Contents
What is the event service?What a payload looks likeField DescriptionSignatureEventsHow to set up your event service urlHow to subscribe to specific eventsWhat is the event service?
The Uberall Event Service allows our application to send specific events to partners. This is done by sending a http-post to a url provided by the partner for all subscribed events. The events currently supported are:
Type |
Description |
LISTING_SYNC_CHECK |
a listing was sync checked, includes possible status changes |
| LISTING_LINK_CHANGED | the url of a listing has changed |
LISTING_DATAPOINT_CHECK |
new datapoints for a listing have been found |
| LISTING_UPDATE | listing's data was attempted to be submitted to the directory |
LOCATION_CREATED |
a location has been created |
LOCATION_STATUS_CHANGED |
a location's status has changed |
LOCATION_PROFILE_CHANGE |
a location has been updated by a user |
BUSINESS_PRODUCT_PLAN_CHANGED |
a business (and its subsequent locations) has changed product plans |
| BUSINESS_CREATED | a business has been created |
The target URL and the subscribed events can be changed during runtime. In case the transmission of an event fails, the system will retry a few times and then discard the event.
What a payload looks like
{
"event": {
"comment": "Location profile has been updated",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_PROFILE_CHANGED",
"user": "user@test.com"
},
"signature": "X"
}All JSON payloads will always have the event and signature fields.
Field Description
Event
Events are the actual payload of the event and differ a bit depending on the event’s type. The common fields are:
Field |
Description |
Comment |
id |
unique id of the event being sent |
can be used to make sure no events ever are handled twice |
time |
the time the event occurred |
|
type |
the type of events |
see above description for possible values |
| listing | the id of the listing the event relates to |
|
location |
the id of the location the event relates to |
can be used to react to the event and e.g. get the new location data after a change |
| business | the id of the business the event relates to |
can be used to react to the event and e.g. get the new business after its creation |
| salesPartnerIdentifier | the identifier of the partner account |
can be used to react to the event and e.g. identify in which account the object was created (if you manage several) |
All other fields are different per event type and described further down.
Signature
The signature is calculated by casting the event field to a String and then HMAC_SHA256 encrypted using the sales partners privatekey and BASE64 encode the result. The events fields need to be ordered alphabetically before decoding!
Pseudo Code:
let json = {"asd": "qwe", "foo": "bar"};
let str = json.encodeAsJson();
assert str === '{"asd": "qwe", "foo": "bar"}';
let privateKey = "this-is-a-secret-key"
let encrypted = hmacShaEncrypt(privateKey, str)
let signature = encrypted.encodeAsBase64()
assert signature === 'UAQuAderRxKW8nMPhyU8oVhS6U8PgG8d/I03lcbNAG4='
Events
LISTING_SYNC_CHECK
Indicates that any of the three main listing statuses (Claim, Flow, Sync) changed.
{
"signature": "X",
"event": {
"claimStatusChanged": false,
"directoryType": "ABCLOCAL",
"flowStatusChanged": true,
"fromListingClaimStatus": "CLAIMED_BY_US",
"fromListingFlowStatus": "ALL_INFORMATION_SUBMITTED",
"fromListingSyncStatus": "NOT_IN_SYNC",
"id": 213581003,
"listing": 332874,
"location": 34838,
"syncStatusChanged": true,
"time": "2016-05-03T10:42:06.000+02:00",
"toListingClaimStatus": "CLAIMED_BY_US",
"toListingFlowStatus": "NO_ACTION_NEEDED",
"toListingSyncStatus": "IN_SYNC",
"type": "LISTING_SYNC_CHECK"
}
}
Field |
Type |
Description |
directoryType |
the directory this listing belongs to |
|
claimStatusChanged |
boolean |
indicating whether the claim status changed |
flowStatusChanged |
boolean |
indicating whether the flow status changed |
syncStatusChanged |
boolean |
indicating whether the sync status changed |
fromListingClaimStatus |
the previous ClaimStatus |
|
fromListingFlowStatus |
FlowStatus |
the previous FlowStatus |
fromListingSyncStatus |
the previous SyncStatus |
|
toListingClaimStatus |
the new ClaimStatus |
|
toListingFlowStatus |
FlowStatus |
the new FlowStatus |
toListingSyncStatus |
the new SyncStatus |
LISTING_STATUS_CHANGE
Indicates that the status of a listing was changed manually. This happens rarely and often is the result of a manual check by our Operations or Engineering teams.
{
"signature": "X",
"event": {
"claimStatusChanged": false,
"directoryType": "ABCLOCAL",
"flowStatusChanged": true,
"fromListingClaimStatus": "CLAIMED_BY_US",
"fromListingFlowStatus": "NO_ACTION_NEEDED",
"fromListingSyncStatus": "NOT_IN_SYNC",
"id": 213581003,
"listing": 332874,
"location": 34838,
"syncStatusChanged": false,
"time": "2016-05-03T10:42:06.000+02:00",
"toListingClaimStatus": "CLAIMED_BY_US",
"toListingFlowStatus": "SUBMISSION_NEEDED",
"toListingSyncStatus": "NOT_IN_SYNC",
"type": "LISTING_STATUS_CHANGE",
"user": "user@uberall.com"
}
}
| Field | Type | Description |
directoryType |
string |
the directory this listing belongs to |
claimStatusChanged |
boolean |
indicating whether the claim status changed |
flowStatusChanged |
boolean |
indicating whether the flow status changed |
syncStatusChanged |
boolean |
indicating whether the sync status changed |
fromListingClaimStatus |
the previous ClaimStatus |
|
fromListingFlowStatus |
FlowStatus |
the previous FlowStatus |
fromListingSyncStatus |
the previous SyncStatus |
|
toListingClaimStatus |
the new ClaimStatus |
|
toListingFlowStatus |
FlowStatus |
the new FlowStatus |
toListingSyncStatus |
the new SyncStatus |
|
user |
string |
the user that changed the status |
LISTING_LINK_CHANGED
Indicates the url of a listing changed, so the Uberall listing is now pointing to a different directory listing. This can either happen by a manual trigger or automatically, if our sync check found a more suitable listing on the directory side than the previously linked one.
{
"event": {
"business": 1234,
"comment": "Listing link changed",
"fromListingId": "456",
"fromListingUrl": "http://old-listing.url/456",
"id": 5549734563,
"listing": 2345,
"location": 3456,
"time": "2019-11-18T14:12:36.000+01:00",
"toListingId": "789",
"toListingUrl": "http://new-listing.url/789",
"type": "LISTING_LINK_CHANGE"
},
"signature": "X"
}
Field |
Type |
Description |
fromListingUrl |
string |
the old listing url |
| fromListingId | string | the old external id of the listing |
| toListingUrl | string | the new listing url |
| toListingId | string | the new external id of the listing |
LISTING_DATAPOINT_CHECK
Indicates that while doing a check for datapoints (i.e. customer feedback such as reviews, photos, etc.), we found new ones.
{
"event": {
"biusiness": 1420951,
"directoryType": "JUDYS_BOOK"
"id": 213580990,
"listing": 332874,
"location": 34838,
"newCheckinsFound": 1,
"newCommentsFound": 1,
"newConversationsFound": 1,
"newDatapointsFound": true,
"newPhotosFound": 1,
"newQuestionsFound": 1,
"newReviewsFound": 1,
"time": "2016-05-03T10:19:14.000+02:00",
"type": "LISTING_DATAPOINT_CHECK"
},
"signature": "X"
}
Field |
Type |
Description |
| directoryType | string | the directory this listing belongs to |
newPhotosFound |
integer |
the number of new photos found |
newReviewsFound |
integer |
the number of new reviews found |
newCheckinsFound |
integer |
the number of new checkins found |
newConversationsFound |
integer |
the number of new conversations found |
newCommentsFound |
integer |
the number of new comments found |
newQuestionsFound |
integer |
the number of new questions found |
LISTING_UPDATE
Indicates that we tried to submit the listing to the directory.
{
"event": {
"business": 7141,
"directoryType": "BING",
"id": 17518447719,
"listing": 7198166,
"location": 450978,
"messages": [
"Listing was updated successfully!"
],
"time": "2021-10-27T16:21:14.000+02:00",
"type": "LISTING_UPDATE",
"updateResult": "SUCCESS",
"updateStatus": null
},
"signature": "X"
}
Field |
Type |
Description |
| directoryType | string | The directory's listing type which we tried to submit |
updateResult |
string |
|
| updateStatus | string | null if updateResult = SUCCESS. Else can be one of: MANDATORY_FIELD_MISSING, // one or more fields are mandatory, but are not set in the location
NOT_SUPPORTED, // the listing is not supported on that directory (e.g. INSTAGRAM -> we only have listing URLs without any direct submission)
INVALID_CLAIM_STATUS, // claim status is invalid (e.g. CLAIMED_BY_OTHERS, but we can only update CLAIMED_BY_US)
INVALID_FLOW_STATUS, // flow status is invalid (e.g. NEEDS_REVIEW)
INVALID_SYNC_STATUS, // sync status is invalid (e.g we cannot update listing that have TECHNICAL_PROBLEMS)
INVALID_LOCATION_STATUS, // location status is invalid (e.g. NEEDS_REVIEW)
LOCATION_NOT_NORMALIZED, // location is not normalized
DUPLICATED, // listing is duplicated, we should not display the logging event as a failure, as there's been no error. see CylexUpdateService#update
LIMIT_REACHED, // can be used when the update fails for throttling or for limits set by the directory
ADDRESS_DISPLAY_NOT_SUPPORTED, // directory doesn't support address display
LOCATION_NOT_SYNCED, // the location of the listing has not been synced yet
LOCATION_NOT_CLEANSED, // the location has not been cleansed yet so we shouldn't push data to some directories that require cleansing-only
DELAYED, // the sync was delayed to a later point in time because of directory restrictions
|
LOCATION_CREATED
Indicates that a new location has been created in your Uberall account.
{
"event": {
"comment": "A new Location has been created",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_CREATED",
"source": "API"
},
"signature": "X"
}
Field |
Type |
Description |
source |
string |
one among [API, CHECKOUT, CSV_UPLOAD, DEMO_JOB, LOCATION_DATA_DOWNLOAD] |
LOCATION_STATUS_CHANGED
Indicates that the status of a location changed.
{
"event": {
"comment": "Checked and activated by a human being.",
"from": "ACTIVE",
"id": 213580999,
"location": 34838,
"time": "2016-05-03T10:34:43.000+02:00",
"to": "CANCELLED",
"type": "LOCATION_STATUS_CHANGED",
"user": "user@uberall.com"
},
"signature": "X"
}
Field |
Type |
Description |
from |
the previous LocationStatus |
|
to |
the new LocationStatus |
|
user |
string |
the user who changed the status (if it was a manual change) |
LOCATION_PROFILE_CHANGE
Indicates that a user changed data of a location.
{
"event": {
"comment": "Location profile has been updated",
"id": 2926113683,
"location": 636605,
"time": "2018-11-05T17:35:07.000+01:00",
"type": "LOCATION_PROFILE_CHANGED",
"user": "user@uberall.com"
},
"signature": "X"
}
Field |
Type |
Description |
user |
string |
the user that changed the data |
BUSINESS_PRODUCT_PLAN_CHANGED
Indicates that a user, privateKey or our system changed the ProductPlan of a Business and its assigned Locations
{
"event": {
"business": 1,
"comment": "Business product plan has been changed",
"id": 5136210330,
"salesPartnerIdentifier": "identifier",
"newProductPlanId": 2,
"newProductPlanName": "My Product Plan 2",
"newProductPlanPrice": 20,
"oldProductPlanId": 1,
"oldProductPlanName": "My Product Plan 1",
"oldProductPlanPrice": 10,
"time": "2019-10-09T15:10:01.000+02:00",
"type": "BUSINESS_PRODUCT_PLAN_CHANGED",
"changedBy": "user@uberall.com"
},
"signature": "XYZ"
}
Field |
Type |
Description |
newProductPlanId |
Long |
the id of newly assigned ProductPlan |
newProductPlanName |
String |
the name of the newly assigned ProductPlan |
newProductPlanPrice |
Integer |
the price (in Cent) of newly assigned ProductPlan |
oldProductPlanId |
Long |
the id of the previously assigned ProductPlan |
oldProductPlanName |
String |
the name of the previously assigned ProductPlan |
oldProductPlanPrice |
Integer |
the price (in Cent) of the previously assigned ProductPlan |
changedBy |
String |
Either one of the following, indicating who triggered the change: |
BUSINESS_CREATED
Indicates that a new Business has been created in the partner account
{
"event": {
"business": 631498,
"changedBy": "PRIVATE_TOKEN",
"comment": "New business has been created",
"id": 5385813249,
"salesPartnerIdentifier": "identifier",
"time": "2019-11-07T16:30:19.000+01:00",
"type": "BUSINESS_CREATED"
},
"signature": "X”
}
Field |
Type |
Description |
changedBy |
String |
Either one of the following, indicating who triggered change: |
How to set up your event service url
Once you have created the endpoint url you wish to receive the events to, you have to set (or change) it via updating the push URL with our API.
You can reach out to api@uberall.com for support.
How to subscribe to specific events
As soon as the push URL is set up, you can subscribe to specific events. By default though, you will initially be subscribed to all event types (see list above).
If you want to get a full list of all subscribable event types, you can check the list with this endpoint.
If you want to change the subscribed event types, you can use the Update a single SalesPartner API endpoint. You will then only receive push messages for the events you have selected.