A WebHook In (also known as incoming WebHook) allows data within Orca Scan to be updated by an external system as events happen.
Every Orca sheet has its own unique WebHook In URL; external systems can send data to this URL to add, update or delete a row within a sheet.
Data must be sent as an HTTP POST in JSON format and contain a ___orca_action
key, for example:
The following example adds a new row to a sheet, setting the value of Barcode, Name, Quantity and Description:
{
"___orca_action": "add",
"Barcode": "0123456789",
"Name": "New 1",
"Quantity": 12,
"Description": "Add new row example"
}
The following example updates an existing row in a sheet, setting the Quantity to 75 where the Barcode = 8511207696421
{
"___orca_action": "update",
"Barcode": "8511207696421",
"Quantity": 75
}
Note: if the row to be updated does not exist, a new row is created.
The following example deletes a row from a sheet where Barcode = 8511207696421
{
"___orca_action": "delete",
"Barcode": "8511207696421"
}
The following example adds two rows and deletes one, with one request:
[
{
"___orca_action": "add",
"Barcode": "0123456789",
"Name": "New 1",
"Quantity": 12,
"Description": "Add new row example"
},
{
"___orca_action": "add",
"Barcode": "9876543210",
"Name": "New 2",
"Quantity": 19
},
{
"___orca_action": "delete",
"Barcode": "8511207696421",
}
]
In order to create a Webhook In, you only need to send a POST request to the URL that you have been given with the action desired and the data of the object in JSON format as explained above.
As can be observed, in the following example snippets you will need to access the /trigger-webhook-in
route on your server in order to launch the request.
app.get('/trigger-webhook-in', function(request, response) {
// the following example adds a new row to a sheet
const json = JSON.stringify(
{
"___orca_action": "add",
"Barcode": "0123456789",
"Name": "New 1",
"Quantity": 12,
"Description": "Add new row example"
}
);
// TODO: change url to https://api.orcascan.com/sheets/{id}
const res = await axios.post("https://httpbin.org/post", json, {
headers: {
// Overwrite Axios's automatically set Content-Type
'Content-Type': 'application/json'
}
});
response.sendStatus(200);
});
[ApiController]
[Route("/trigger-webhook-in")]
public class OrcaWebHookInDotNet : ControllerBase
{
[HttpGet]
public async Task<OkResult> WebHookTrigger()
{
// the following example adds a new row to a sheet
// setting the value of Barcode, Name, Quantity and Description
// TODO: change url to https://api.orcascan.com/sheets/{id}
string url = "https://httpbin.org/post";
string json = "{\"___orca_action\":\"add\",\"___orca_sheet_name\":\"Sheet1\",\"Barcode\":\"123456789\",\"Name\":\"Test\",\"Quantity\":\"1\",\"Description\":\"Test\"}";
// send post request
var client = new HttpClient();
var content = new StringContent(json, Encoding.UTF8, "application/json");
var result = await client.PostAsync(url, content);
// if response ok print it
if (result.IsSuccessStatusCode)
{
var response = await result.Content.ReadAsStringAsync();
Console.WriteLine(response);
}
return Ok();
}
}
func webHookInHandler(w http.ResponseWriter, r *http.Request) {
values := map[string]string{
"___orca_action": "add",
"Barcode": "0123456789",
"Name": "New 1",
"Quantity": "12",
"Description": "Add new row example",
}
jsonValue, _ := json.Marshal(values)
// The following example adds a new row to a sheet
// setting the value of Barcode, Name, Quantity and Description
// TODO: change url to https://api.orcascan.com/sheets/{id}
response, err := http.Post("https://httpbin.org/post", "application/json", bytes.NewBuffer(jsonValue))
if err != nil {
// read response error
fmt.Println(err)
}
else {
// read response body
body, _ := ioutil.ReadAll(response.Body)
data := map[string]string{}
jsonErr := json.Unmarshal([]byte(body), &data)
if jsonErr != nil {
return
}
fmt.Println(data)
}
w.WriteHeader(http.StatusOK)
w.Write([]byte("OK"))
return
}
@app.route('/trigger-webhook-in', methods=['GET'])
def trigger_webhook_in():
# the following example adds a new row to a sheet
# setting the value of Barcode, Name, Quantity and Description
# TODO: change url to https://api.orcascan.com/sheets/{id}
response = requests.post('https://httpbin.org/post', json={
"___orca_action": "add",
"Barcode": "0123456712",
"Name": "New 1",
"Quantity": 12,
"Description": "Add new row example"
})
if response.ok:
print(response.content)
return "ok"
if (preg_match('/trigger-webhook-in$/', $_SERVER["REQUEST_URI"])) {
if ($_SERVER['REQUEST_METHOD'] === 'GET') {
// The following example adds a new row to a sheet
// setting the value of Barcode, Name, Quantity and Description
$data = array(
"___orca_action" => "update",
"barcode" => "0123456789",
"Name" => "New 1",
"Quantity" => 12,
"Description" => "Add new row example"
);
// TODO: change url to https://api.orcascan.com/sheets/{id}
$url = 'https://httpbin.org/post';
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen(json_encode($data))
));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
}
}
@RequestMapping(
value = "/trigger-webhook-in",
method = RequestMethod.GET)
String triggerWebhookIn() throws Exception {
RestTemplate restTemplate = new RestTemplate();
// The following example adds a new row to a sheet
// setting the value of Barcode, Name, Quantity and Description
// TODO: change url to https://api.orcascan.com/sheets/{id}
String url = "https://httpbin.org/post";
JSONObject json = new JSONObject();
json.put("___orca_action", "add");
json.put("Barcode", "0123456789");
json.put("Name", "New 1");
json.put("Quantity", 12);
json.put("Description", "Add new row example");
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
HttpEntity<String> entity = new HttpEntity<String>(json.toJSONString(), headers);
String answer = restTemplate.postForObject(url, entity, String.class);
System.out.println(answer);
return "ok";
}
A fully working version for all programming languages can be found on GitHub.
To get the unique WebHook In URL for a sheet, simply:
Select the relevant sheet or create a new one
Open sheet Integrations from the toolbar
Activate WebHook In by clicking the on the toggle.
Click copy to the right of the WebHook In URL to copy the value to your clipboard.
You can now share this URL to allow developers/systems to update your barcode data.
You can secure your WebHook In by providing a secret. When set, the HTTP Header orca-secret
must be provided with each request. Requests that do not match the secret set on your sheet will be rejected with a 403 Forbidden.
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.