Overview‎ > ‎

Callbacks

Callbacks allow you to receive a notification when specific events occur on the proof. Events include:
  • New comment
  • Reply to a comment
  • Change of proof state
  • New or changed decision
  • Changed comment action
  • Proof processing succeeded / failed
  • Proof trashed / permanently deleted
  • Proof archived / unarchived
The notification is made by performing a POST of XML data containing basic information regarding the event.


Examples

New comment

<?xml version="1.0"?>
    <callback type="comment">
        <comment_id>751</comment_id>
        <file_id>242</file_id>
        <author>Irek Kubicki</author>
        <comment>Comment</comment>
        <action />
        <timestamp>1234567890</timestamp>
        <proof_name>MyFile.pdf</proof_name>
        <recipient_id>34543</recipient_id>
        <author_email>irek@proofhq.com</author_email>   
        <folder_id>5432</folder_id>   
        <folder_name>MyFolder</folder_name>              
    </callback>

Reply to a comment

<?xml version="1.0"?>
    <callback type="reply">
        <reply_id>383</reply_id>
        <comment_id>751</comment_id>
        <file_id>242</file_id>
        <author>Irek Kubicki</author>
        <comment>Comment</comment> 
        <reply>Reply</reply> 
        <action>TO DO</action> 
        <timestamp>1234567890</timestamp>
        <proof_name>MyFile.pdf</proof_name>  
        <recipient_id>34543</recipient_id>
        <author_email>irek@proofhq.com</author_email>   
        <folder_id>5432</folder_id>   
        <folder_name>MyFolder</folder_name>              
    </callback>

Change of proof state

<?xml version="1.0"?>
    <callback type="state">
        <file_id>242</file_id>
        <name>globe.png</name>
        <state>unlocked</state>
        <status>pending</status>
        <folder_id>2343</folder_id>
        <folder_name>My Folder</folder_name>
    </callback>

Action change on comment

<?xml version="1.0"?>
    <callback type="action">
        <comment_id>751</comment_id >
        <file_id>242</file_id>
        <author>Irek Kubicki</author>
        <comment>Comment</comment>
        <action>TO DO</action>
        <timestamp>1234567890</timestamp>
        <proof_name>MyFile.pdf</proof_name>  
        <recipient_id>34543</recipient_id>
        <author_email>irek@proofhq.com</author_email>   
    </callback>

Decision made or changed

<?xml version="1.0"?>
    <callback type="decision">
        <recipient_id>400</recipient_id>
        <file_id>242</file_id>
        <name>Irek Kubicki</name>
        <decision>changes required</decision>
        <proof_name>MyFile.pdf</proof_name>  
        <folder_id>2343</folder_id>
        <folder_name>My Folder</folder_name>
        <recipient_id>34543</recipient_id>
        <author_email>irek@proofhq.com</author_email>   
    </callback>

Processed

<?xml version="1.0"?>
    <callback type="processed">
        <file_id>242</file_id>
        <name>TheProofName.pdf</name>
        <status>success</status> OR <status>failed</status>
        <folder_id>2343</folder_id>
        <folder_name>My Folder</folder_name>
    </callback>

Trashed

<?xml version="1.0"?>
    <callback type="trashed">
        <file_id>242</file_id>
        <parent_file_id>4567</parent_file_id>
        <timestamp>1234567890</timestamp>

        <proof_name>TheProofName.pdf</proof_name>
        <user_action_id>4543</user_action_id>
        <user_action_email>irek@proofhq.com</user_action_email>

        <folder_id>2343</folder_id>
        <folder_name>My Folder</folder_name>
    </callback>

Permanently deleted

<?xml version="1.0"?>
    <callback type="deleted">
        <file_id>242</file_id>
        <parent_file_id>4567</parent_file_id>    
        <timestamp>1234567890</timestamp>

        <proof_name>TheProofName.pdf</proof_name>
        <user_action_id>4543</user_action_id>
        <user_action_email>irek@proofhq.com</user_action_email>

        <folder_id>2343</folder_id>
        <folder_name>My Folder</folder_name>
    </callback>

Archived

<?xml version="1.0"?>
    <callback type="archived">
        <file_id>242</file_id>
        <name>TheProofName.pdf</name>

        <archived>true</archived> OR <archived>false</archived>
        <status>pending</status>
        <folder_id>2343</folder_id>

        <folder_name>My Folder</folder_name>
    </callback>


With the release of the 13.14 WSDL we have introduced a pass through parameter that can be used when either creating a new proof or creating a new version. With this parameter you are able to pass through a value that will be returned when a callback is made on this new proof or version 
e.g. Creating a proof with the pass_through parameter

https://app.proofhq.com/newproof?pass_through=xxx

will result in the following "New comment" callback (and applies to all other callbacks using the pass_through parameter):

<?xml version="1.0"?>
    <callback type="comment">
        <comment_id>751</comment_id>
        <file_id>242</file_id>
        <author>Irek Kubicki</author>
        <comment>Comment</comment>
        <action />
        <timestamp>1234567890</timestamp>
        <proof_name>MyFile.pdf</proof_name> 
             <pass_through>"xxx"</pass_through> 
    </callback>

Note the JSON encoded pass_through parameter that is included in the callback xml. This will allow you to link an entity within your system to the proof within ProofHQ by passing in the identifier associated with this entity. The same applies for new versions 
e.g. Creating a new version with the pass_through parameter

https://app.proofhq.com/upload/version/xyz?pass_through=xxx

Where "xyz" is the id of the proof you want create a new version on and "xxx" is your pass through parameter.