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).

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.

API callbacks have the following syntax:

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

where component is the notification "type" or source.

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)

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=http://domain.fake/your_work_url
&status=404
&signature=b43f1942381b9ea77449932478e488e4ff43a244

• component: workdownload
• code: work code
• url: URL where the work was tried to be downloaded from
• status: HTTP status code received when trying to download the work

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 a user account using the user.link component, you will receive this callback whenever the user modifies his Safe Creative account.

?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: authkeys of the user. A user can 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