How to update your system from Orca Scan


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 adds, updates or deletes any item, Orca sends an HTTP POST with the data for that item (in JSON format) to the unique URL you specify.


What information does Orca Scan send?

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 VIN barcode, enters the required information and taps save, that information is saved to your Orca sheet, but also sent to your WebHook Out URL in the following format:

{
    "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"
}

As you would expect, a value will exist for each column in your sheet, but we also include a few extra fields to help your system to make sense of the event, these fields are prefixed with ___orca_

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

HTTP Headers

Orca also sends the following HTTP headers with every request:

Key Type Description
orca-sheet-name string Name of the sheet
orca-user-email string Email address of the user who triggered the action (requires a HTTPS connection)
orca-timestamp number timestamp of the request in UNIX epoch format
orca-secret string Secret value if set on your sheet (check this to verify request is coming from your sheet)

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

Create a new sheet in your Orca Scan account
Create a new sheet in your Orca Scan account

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


2. Edit Sheet Integrations

Click on 'integrations' button at the top of the sheet
Click on 'integrations' button at the top of the sheet

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


3. Add your WebHook Out URL

Add the URL you'd like to be notified about your data changes
Add the URL you'd like to be notified about 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

Test your WebHook Out URL by clicking the 'Test' button and 'OK'
Test your WebHook Out URL by clicking the 'Test' button and 'OK'

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?