Saas Callback

Saas provides a callback mechanism to notify your server about events that have occurred.

To configure a callback, you must configure a CALLBACK URL on your account.

This url will be called for each event, passing any additional event information in a json body.

The callback request is currently signed with the clients guid and a generated shared secret key.

This adheres to the policy defined by the API auth gem:

  1. A canonical string is first created using HTTP headers containing the content-type, content-MD5, request URI and the timestamp. If content-type or content-MD5 are not present, then a blank string is used in their place. If the timestamp isn’t present, a valid HTTP date is automatically added to the request. The canonical string string is computed as follows: canonical_string = 'content-type,content-MD5,request URI,timestamp'

  2. This string is then used to create the signature which is a Base64 encoded SHA1 HMAC, using the client’s private secret key.

  3. This signature is then added as the Authorization HTTP header in the form: Authorization = APIAuth 'client access id':'signature from step 2'

  4. The SHA1 HMAC is computed in the same way using the request headers and the client’s secret key, which is known to only the client and the server but can be looked up on the server using the client’s access id that was attached in the header. The access id can be any integer or string that uniquely identifies the client. The signed request expires after 15 minutes in order to avoid replay attacks.

An example implementation to receive the callback follows (using Rails and API Auth Gem):

 ##
 #== POST /api_v1/saas_callback
 #saas calls us back with events

 #=== Success
 #[200] OK

 #=== Failure
 #[423] Invalid app_client_api_key
 #[500] Generic Server Exception
 #[501] Database error

 def saas_callback
   client_app_api_key = ApiAuth.access_id(request)
   raise ApiException.new 460, "Authentication Required" unless ApiAuth.authentic? request, shared_secret
   events = params[:events]
     DO SOMETHING WITH EVENTS
   render text: "OK#{params}"   
 end

The following events currently generate callbacks:

MESSAGE EVENTS

message_success - message was created

Passed JSON Body

event::  message_success
message_tsui::  message guid
has_video:: whether message has attached video
sender_tsui:: sender tsui
recipient_tsui_list::  list of recipients
unread_message_count::

message_read - message was read

Passed JSON Body

event::message_read
recipient_tsui:: recipient tsui
sender_tsui::  sender tsui
message_tsui::  message guid

destroy - message was destroyed

Passed JSON Body

event::destroy
recipient_tsui_list:: recipient list
sender_tsui::  sender tsui
message_tsui::  message guid

hidden - message was hidden

Passed JSON Body

event::hidden
tsui:: sender tsui
message_tsui::  message guid

forward - message has been forwarded

Passed JSON Body

event::forward
recipient_tsui::  recipient tsui
sender_tsui::  sender tsui
message_tsui::  message tsui

yanked - recall sent message from recipient

Passed JSON Body

event::yanked
recipient_tsui_list::  recipient list
sender_tsui::  sender tsui
message_tsui::  message tsui

unread_message_count - TBD

Passed JSON Body

event::unread_message_count
tsui::  sender tsui
unread_message_count::  unread_message_count

screenshot - Mobile client has notified of screenshot

Passed JSON Body

event::screenshot
recipient_tsui::  sender tsui
sender_tsui::  unread_message_count
message_tsui::  unread_message_count

VIDEO EVENTS

video_processed - Video has been successfully transcoded and is available

Passed JSON Body

event::video_processed
video_processed::  video guid

video_failed - Video failed transcoding

Passed JSON Body

event::video_failed
video_processed::  video guid