API callbacks

The Safe Creative API can sometimes send your application different notifications through your callback URL, which you can enter when you request you API keys (or edit at any moment once your API key has been activated).

You may receive the same notification more than once, though it is not common.

Syntax

API callbacks have the following syntax:

{your callback URL}
?component=...
&ztime=...
&<callback parameters>
&signature=...

Where component is the notification "type" or source.

The callback is signed with the private key associated to your shared key and is ztime-stamped so you can verify the authenticity of the call. It's recommeded to define the callback url as HTTPS.

Callback types

Notification of a work state change

Used to notify when a work registered through your application has changed its state. Usually this means that its pre-registration period has finished or that a work registered by URL has been successfully downloaded.

{your callback URL}
?component=workstate
&ztime=1248523203872
&code=0907240000817
&state=REGISTERED
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: workstate for this type of callback
• code: is the work code
• state: current state of the work. May be PREREGISTERED or REGISTERED
  • PREREGISTERED: The work was registered by URL, has been downloaded and enters its pre-registration period
  • REGISTERED: The work has finished its pre-registrations period (or was registered as final)

Notification of work deletion

Used to notify when a work registered through your application has been deleted by the author.

{your callback URL}
?component=workdeleted
&ztime=1248523203872
&code=0907240000817
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: workdeleted for this type of callback
• code: is the work code

URL registration failure

If you register a work by URL and the work file cannot be downloaded after some retries, you will receive this callback.

{your callback URL}
?component=workdownload
&ztime=1248523203872
&code=0907240000817
&url={your_work_url}
&status=failed
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: workdownload
• code: work code
• url: URL where the work was tried to be downloaded from
• status: Status code
  • failed: Download has failed
  • filesize-mismatch: Downloaded file size does not match the one provided
  • checksum-mismatch: Downloaded file checksum does not match the one provided
  • notfound: Work has been deleted before download was completed
  • unexpected-workstate: Work is in an unexpected registation state
  • already-registered: Work is already registered
  • unauthorized: The api key used to register this work is not authorized
  • missing-auth: The api key used to register this work is not available

URL registration failure: authorization missing

If you register a work by URL and the user authorization cannot be found (Eg: It's changed), you will receive this callback.

{your callback URL}
?component=workdownload
&ztime=1248523203872
&authkey=23j22wtpoguzgzk0fag39sey6
&status=missing-auth
&code=0907240000817
&url={your_work_url}
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: workdownload
• authkey: authkey of the user's authorization
• status: can only be missing-auth

User authorization deleted

One of your users has deleted his authorization to your application

{your callback URL}
?component=authorization
&ztime=1248523203872
&authkey=23j22wtpoguzgzk0fag39sey6
&state=deleted
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: authorization
• authkey: authkey of the deleted authorization
• state: current state of the authorization (can only be deleted)

User personal data modified

If you are a partner and have created an user account using the user.link component, you will receive this callback whenever the user modifies his Safe Creative account.

{your callback URL}
?component=user
&ztime=1248523203872
&authkey=5ykfbzoe5h6viy88texq7gay2
&state=modified
&code=0907090000074
&mail=sholmes%40baker.fake
&firstName=Sherlock
&middleName=
&lastName=Holmes
&addressLine1=221B+Baker+Street
&addressLine2=City+of+Westminster
&addressCity=London
&addressCountry=GB

• component: user
• authkey: authkey of the user. A user may have more than one authkey for your application. In that case, this parameter will be repeated for each authkey.
• state: state of the user (always modified)
• code: user's code
• mail, firstName, middleName, lastName, addressLine1, addressLine2, addressCity, addressCountry: user's current data

User deleted

If you are a partner and have created an user account using the user.link component, you will receive this callback whenever the user deletes his Safe Creative account.

{your callback URL}
?component=user
&ztime=1248523203872
&authkey=5ykfbzoe5h6viy88texq7gay2
&state=deleted
&code=0907090000074
&mail=sholmes%40baker.fake

• component: user
• authkey: authkey of the user. A user may have more than one authkey for your application. In that case, this parameter will be repeated for each authkey.
• state: state of the user (always deleted)
• code: user's code
• mail: user's current data