Updating your system data when a barcode is scanned


What is a WebHook Out?

A WebHook Out (also known as outgoing WebHook) allows software systems to notify external applications as events happen in real-time.


How does a WebHook Out work?

When an Orca Scan user performs an action such as add, update or delete, Orca sends an HTTP POST with the data for that item in JSON format a URL you provide.


What information does Orca Scan send when I add, update or delete data?

Let’s say you’re tracking vehicles; you create a sheet named Vehicle Checks with VIN, Make, Model, Year, Location, Condition and Notes columns and share that sheet with members of your team.

When a teammate scans a barcode, enters the required information and taps save, the following data is saved to your sheet and sent to your URL. The ___orca_action property will vary depending on the performed action.

{
    "VIN": "4S3BMHB68B3286050",
    "Make": "SUBARU",
    "Model": "Legacy",
    "Model Year": "2011",
    "Condition": "Poor",
    "Location": "52.2034823, 0.1235817",
    "Notes": "Needs new tires",
    "___orca_action": "add",
    "___orca_sheet_name": "Vehicle Checks",
    "___orca_user_email": "hidden@requires.https",
    "___orca_row_id": "5cf5c1efc66a9681047a0f3d"
}

We include a few extra fields prefixed with ___orca_ to help you make sense of the event:

Key Type Description
___orca_row_id string Unique row ID
___orca_user_email string The registered email address of the user who performed the action - requires an HTTPS connection
___orca_action string The type of action that was performed. Values include add, update, delete and test, import:append, import:replace, clear:column, clear:sheet
___orca_sheet_name string Name of the sheet

What information does Orca Scan send when I import data?

If you import data into a sheet, the payload sent to your URL is slightly different. It will contain a nested rows property containing the row data that was imported. The ___orca_action field will contain either import:append or import:replace depend on the Action selected during import.

{
    "___orca_action": "import:replace",
    "___orca_sheet_name": "Sheet1",
    "___orca_user_email": "name@email.com",
    "rows": [
        {
            "Barcode": "757483456",
            "Name": "John",
            "Location": "",
            "Date": "",
            "quantity": "1",
            "___orca_row_id": "5cf5c1efc66a9681047a0f31"
        },
        {
            "Barcode": "12537468",
            "Name": "Owen",
            "Location": "",
            "Date": "",
            "quantity": "2",
            "___orca_row_id": "5cf5c1efc66a9681047a0f32"
        },
        {
            "Barcode": "85636462",
            "Name": "Rhys",
            "Location": "",
            "Date": "",
            "quantity": "3",
            "___orca_row_id": "5cf5c1efc66a9681047a0f33"
        }
}

What information does Orca Scan send when I clear data?

If you clear a column, Orca Scan sends the following payload:

{
    "___orca_action": "clear:column",
    "___orca_sheet_name": "Sheet1",
    "___orca_user_email": "name@email.com",
    "___orca_column_name": "Name"
}

If you clear a sheet, Orca Scan sends the following payload:

{
    "___orca_action": "clear:sheet",
    "___orca_sheet_name": "Sheet1",
    "___orca_user_email": "name@email.com"
}

HTTP Headers

The following HTTP headers are sent with every request:

Parameter Description
orca-request-type webhook-out
orca-secret Sheet assigned secret (check this to verify request)
orca-sheet-id Unique ID of the Orca Scan sheet
orca-sheet-name Name of the sheet
orca-timestamp timestamp of the request in UNIX epoch format
orca-user-email Email of user who triggered the request (requires HTTPS)

How do I create a WebHook Out?

In order to be able to receive data from Orca Cloud on your system, you have to define an endpoint that accepts POST requests as in the following example snippets. The endpoint used for this example is /orca-webhook-out so, make sure the URL contains this endpoint when adding it to Orca Cloud.

Node.js C# Go Python PHP Java
const express = require('express'); const app = express(); app.use(express.json()); app.post('/orca-webhook-out', function(request, response){ data = request.body; // dubug purpose: show in console raw data received console.log("Request received: \n"+JSON.stringify(data, null, 2)); // get the name of the action that triggered this request (add, update, delete, test) const action = data.___orca_action // get the name of the sheet this action impacts const sheetName = data.___orca_sheet_name // get the email of the user who preformed the action (empty if not HTTPS) const userEmail = data.___orca_user_email // orca system fields start with ___ // access the value of fields using the field name // example: data.Name, data.Barcode, data.Location switch (action) { case "add": // TODO: do something when a row has been added break; case "update": // TODO: do something when a row has been updated break; case "delete": // TODO: do something when a row has been deleted break; case "test": // TODO: do something when the user in the web app hits the test button break; } response.sendStatus(200); }); app.listen(3000, () => console.log('Example app is listening on port 3000.'));
[HttpPost] [Consumes("application/json")] public async Task<OkResult> WebHookReceiver() { // WebHooks send data as a HTTP POST, so extract JSON string from Request.Body using (StreamReader reader = new StreamReader(Request.Body, Encoding.UTF8)) { // get the raw JSON string string json = await reader.ReadToEndAsync(); // convert into .net object dynamic data = JObject.Parse(json); // get the name of the action that triggered this request (add, update, delete, test) string action = (data.___orca_action != null) ? (string)data.___orca_action : ""; // get the name of the sheet this action impacts string sheetName = (data.___orca_sheet_name != null) ? (string)data.___orca_sheet_name : ""; // get the email of the user who preformed the action (empty if not HTTPS) string userEmail = (data.___orca_user_email != null) ? (string)data.___orca_user_email : ""; // orca system fields start with ___ // access the value of fields using the field name // example: data.Name, data.Barcode, data.Location // decide on what action to take based on orca action switch (action) { case "add": { // TODO: do something when a row has been added } break; case "update": { // TODO: do something when a row has been updated } break; case "delete": { // TODO: do something when a row has been deleted } break; case "test": { // TODO: do something when the user in the web app hits the test button } break; } } // always return a 200 (ok) return new OkResult(); }
type OrcaBarcode struct { Barcode string Date string Description string Example string Name string Quantity int ___autofocus string ___autoselect string ___lastSchemaVersion string ___orca_action string ___orca_row_id string ___orca_sheet_name string ___orca_user_email string ___owner string ___schemaVersion string } func webHookOutHandler(w http.ResponseWriter, r *http.Request) { // Read body body, err := ioutil.ReadAll(r.Body) defer r.Body.Close() if err != nil { fmt.Println(err) http.Error(w, err.Error(), 500) return } // Parse JSON data var barcode OrcaBarcode jsonErr := json.Unmarshal([]byte(body), &barcode) if jsonErr != nil { fmt.Println(jsonErr) http.Error(w, jsonErr.Error(), 500) return } // dubug purpose: show in console raw data received fmt.Println(barcode) // get the name of the action that triggered this request (add, update, delete, test) action := barcode.___orca_action // get the name of the sheet this action impacts sheetName := barcode.___orca_sheet_name fmt.Println(sheetName) // get the email of the user who preformed the action (empty if not HTTPS) userEmail := barcode.___orca_user_email fmt.Println(userEmail) // orca system fields start with ___ // access the value of fields using the field name // example: data["Name"], data["Barcode"], data["Location"] switch action { case "add": // TODO: do something when a row has been added case "update": // TODO: do something when a row has been updated case "delete": // TODO: do something when a row has been deleted case "test": // TODO: do something when the user in the web app hits the test button } w.WriteHeader(http.StatusOK) w.Write([]byte("OK")) return }
@app.route('/orca-webhook-out', methods=['POST']) def webhook_out(): if request.method == 'POST': data = request.get_json() # get the name of the action that triggered this request (add, update, delete, test) action = data["___orca_action"] # get the name of the sheet this action impacts sheet_name = data["___orca_sheet_name"] # get the email of the user who preformed the action (empty if not HTTPS) user_email = data["___orca_user_email"] # orca system fields start with ___ # access the value of fields using the field name # example: data["Name"], data["Barcode"], data["Location"] if action == "add": # TODO: do something when a row has been added pass elif action == "update": # TODO: do something when a row has been updated pass elif action == "delete": # TODO: do something when a row has been deleted pass elif action == "test": # TODO: do something when the user in the web app hits the test button pass # always return a 200 (ok) return "ok"
if (preg_match('/orca-webhook-out$/', $_SERVER["REQUEST_URI"])){ if ($_SERVER['REQUEST_METHOD'] === 'POST') { $data = json_decode(file_get_contents('php://input'), true); // get the name of the action that triggered this request (add, update, delete, test) $action = $data["___orca_action"]; // get the name of the sheet this action impacts $sheetName = $data["___orca_sheet_name"]; // get the email of the user who preformed the action (empty if not HTTPS) $userEmail = $data["___orca_user_email"]; // orca system fields start with ___ // access the value of fields using the field name // example: data.Name, data.Barcode, data.Location switch ($action) { case "add": // TODO: do something when a row has been added break; case "update": // TODO: do something when a row has been updated break; case "delete": // TODO: do something when a row has been deleted break; case "test": // TODO: do something when the user in the web app hits the test button break; } return 'ok'; } }
@RequestMapping( value = "/orca-webhook-out", method = RequestMethod.POST) String index(@RequestBody Map<String, Object> payload) throws Exception { // dubug purpose: show in console raw data received System.out.println(payload); // get the name of the action that triggered this request (add, update, delete, test) String action = payload.get("___orca_action").toString(); // get the name of the sheet this action impacts String sheetName = payload.get("___orca_sheet_name").toString(); // get the email of the user who preformed the action (empty if not HTTPS) String userEmail = payload.get("___orca_user_email").toString(); // orca system fields start with ___ // access the value of fields using the field name // example: data.Name, data.Barcode, data.Location switch (action) { case "add": // TODO: do something when a row has been added break; case "update": // TODO: do something when a row has been updated break; case "delete": // TODO: do something when a row has been deleted break; case "test": // TODO: do something when the user in the web app hits the test button break; } return "ok"; }

A fully working version for all programming languages can be found on GitHub.

How do I add a WebHook Out URL to my sheet?

You can add a WebHook Out URL to any Orca Scan sheet using the following steps:

1. Create a new sheet

Start by creating a sheet.
Start by creating a sheet.

Let’s start by creating a sheet named Vehicle Checks using the Vehicle Information template.


2. Edit Sheet Integrations

Once you have created a sheet, open the Integrations tab.
Once you have created a sheet, open the Integrations tab.

With the new sheet selected, open the Integration Settings from the toolbar.


3. Add your WebHook Out URL

You’ll see the WebHook Out bar. Now enter the URL you would like to be called as your data changes.
You’ll see the WebHook Out bar. Now enter the URL you would like to be called as your data changes.

Now enter the URL you would like to be called as your data changes.

Security

You can provide a secret that will be sent to your server as an HTTP header with every request, allowing you to determine if the incoming request is from Orca Scan.


4. Test your WebHook Out

You can test your WebHook Out URL by clicking the 
You can test your WebHook Out URL by clicking the 

You can test your WebHook Out URL by clicking the Test button, this will send test data for every column in your sheet, along with the ___orca_action with the value of test.

To test a WebHook Out without any development, you can use a free service such as RequestBin, simply copy the temporary URL to your sheet and hit test.


5. Save the changes

Finally, save your changes and you’re done. Now every time someone scans a barcode and makes a change, your system will know about it.


WebHook questions?

We’re happy to help troubleshoot any issues you might have connecting Orca Scan to your system, simply chat with us live or drop us an email.


Ready to start scanning?