fbwrkplc-webhook-proposal

fbwrkplc-webhook-proposal.md

Link finalizatin for link collection+preview hook

Comments indicate proposed changes.

link>collection

response:

introduce linkIsFinal

{
  "data": [
    {
      "link": string,
      "linkIsFinal": boolean,      //true by default. 
                                   // if set to false, link>finalize is called after user selects the item and 
                                   // response to link>finalize is saved in the message
      "title": string,
      ?"description": string,
      ?"download_url": string,
      "privacy": ORGANIZATION | ACCESSIBLE,
      "type": DOCUMENT | FOLDER | TASK | LINK,
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

link>finalize webhook call introduced

introduce new webhook call, entry-changes-field=finalize

POST /callback HTTP/1.1
Host: third-party.com
Accept: application/json
Content-Type: application/json
User-Agent: Webhooks/1.0 (https://fb.me/webhooks)
X-Hub-Signature: sha1=bf3102e52efd0fd4bd26277030aa180d7b5cf587

{
    "object": "link",
    "entry": [{
        "time": 1501515097793,
        "changes": [{
            "field": "finalize",           //the only difference between preview and this is the name
            "value": {
                "community": {
                    "id": "138169208138649"
                },
                "user": {
                    "id": "88575656148087"
                }
                "link": "https://company.third-party.com/document-about-this"
            }
        }]
    }]
}

response:

{
  "data": [
    {
      "link": string,
                     //linkIsFinal would be ignored in this response, must be true
      "title": string,
      ?"description": string,
      ?"download_url": string,
      "privacy": ORGANIZATION | ACCESSIBLE,
      "type": DOCUMENT | FOLDER | TASK | LINK,
      ?"additional_data": [
        {
          "title" => string,
          "format" => 'text' | 'date' | 'datetime' | 'user',
          "value" => string | number,
        },
      ],
    }
  ],
  ?"linked_user": boolean
}

Response to this hook is used as the link data instead of the record returned for collection call