Event service documentation (Webhooks)

How to receive event payloads from Uberall

Last updated on July 12th, 2022

What 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

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

ListingClaimStatus

the previous ClaimStatus

fromListingFlowStatus

FlowStatus

the previous FlowStatus

fromListingSyncStatus

SyncStatus

the previous SyncStatus

toListingClaimStatus

ListingClaimStatus

the new ClaimStatus

toListingFlowStatus

FlowStatus

the new FlowStatus

toListingSyncStatus

SyncStatus

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

ListingClaimStatus

the previous ClaimStatus

fromListingFlowStatus

FlowStatus

the previous FlowStatus

fromListingSyncStatus

SyncStatus

the previous SyncStatus

toListingClaimStatus

ListingClaimStatus

the new ClaimStatus

toListingFlowStatus

FlowStatus

the new FlowStatus

toListingSyncStatus

SyncStatus

the new SyncStatus

user

string

the user that changed the status



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

  • SUCCESS - listing has been successfully updated
  • FAILURE - listing update was rejected by directory
  • UNDEFINED - listing data could not be submitted due to some reason outlined in UpdateStatus below
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

Delete

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

LocationStatus

the previous LocationStatus

to

LocationStatus

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:
1. user email
2. “PRIVATE_TOKEN”
3. “SYSTEM”



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:
1. user email
2. “PRIVATE_TOKEN”
3. “SYSTEM”




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.





Was this article helpful?

Save as PDF