An App can subscribe to different events(channels) to be notified without having to poll for changes. Events are organised in channels, where a channel name is made up of the object-type and the action name. There are three kind of actions for each object: create, update, delete.

client.update, invoice.delete, comment.create

All available channels can be found at MY-SUB.salesking.eu/api/subs/channels, which simply returns an array of strings like the above.

Subscription

An app subscribes to a single channel by creating a new subscription object using the API . Subscriptions behave like any API object, so you have all CRUD-methods. 

POST  ../api/subs
{
"sub": {
"channel": "client.create",
"callback_url": "https://my-site-receiving-the-callback.com" }}

The difference is that a subscription is tied to an app and it's current access_token(specific for each user).

Therefore only oAuth apps can subscribe to channels which also applies to CRUD methods!

This is a security measure imposed by our role system. So if a user cannot delete invoices his apps won't receive the callback. If an app is revoked(access_token destroyed), subscriptions are also removed.

Before an app can subscribe to a resource's channels, it needs to have access to the resource(see Permissions). This is done by the scope parameter used when a user grants an app access(see Authentication).

scope=clients:create,update,delete
scope=clients

Contrary to the app-scope needed create clients (api/clients), the notification-scopes are not prefixed with "api/". This is because we don't differentiate between objects created over the API or the interface.

Remember: the scope solely acts as a listener therefore an app cannot access salesking.eu/clients

Examples: App gets notified on client creation and also creates and updates clients

scope=clients:create api/clients:create,update

App gets notified on all client events and also CRUD clients

scope=clients api/clients

Publishing / PushNotification

With the subscription in place, we will make an POST request to the supplied URL whenever the event occurs. Your endpoint should be secure(https) and the provided URL MUST be within your apps URL. 

The request contains a single parameter: signed_request with a dot(.) delimited string(no newlines)

60673142fdda45f3185cbd51c070596950a9178e20f785703723ad8e0ff04833.eyJrZXkiOiJ2YWx1ZSJ9<br>

The first part is a the hmac signature, the second is a base64 URL encoded string with a json object. The example above was created with an input of '{"key":"value"}' and 'secret' as password using the signed_param method from our SDK.

The JSON object looks like this:

{
"obj":{"client":{..},"links":[..]},
"company_id":"c2ew4mSlCr4lENabxfpGMl",
"user_id":"c1339KSlCr4lENabxfpGMl",
"sub_domain":"729831939",
"issued_at":"2011-07-17T21:03:48Z",
"access_token":"bf77b03c31f003f1d852b3e0bac87345",
"expires":"2011-07-17T21:59:50Z",
"algorithm":"HMAC-SHA256"
}

Decoding can be done with our ruby sdk:

a = SK::SDK::SignedRequest.new(signed_param, 'app-secret')
puts a.data.inspect if a.valid?