How to update your system when data changes

Requires a Business subscription plan

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 a HTTP POST with the data for that item (in JSON format) to the unique URL you specify.

What information does Orca Scan send?

Lets 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_action string The type of action that was performed. Values include add, update, delete and test
___orca_sheet_name string Name of the sheet
___orca_user_email string The registered email address of the user who preformed the action - requires a HTTPS connection
___orca_row_id string Unique row ID

HTTP Headers

Orca also sends the following HTTP Headers with every request:

Key Type Description
orca-timestamp number timestamp of the request in UNIX epoch format
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-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 Orca Scan cloud sheet

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

2. Edit Sheet Integrations

Opening the sheet integration menu

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

3. Add your WebHook Out URL

Sheet lookup URL input

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 a HTTP header with every request, allowing you to determine if the incoming request is from Orca Scan.

4. Test your WebHook Out

Sheet lookup test result

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.