{"id":19528499,"url":"https://github.com/orca-scan/orca-validation-node","last_synced_at":"2026-05-17T14:36:33.808Z","repository":{"id":38289047,"uuid":"311140588","full_name":"orca-scan/orca-validation-node","owner":"orca-scan","description":"How to validate barcode scans using Orca Scan and Node.js","archived":false,"fork":false,"pushed_at":"2022-06-25T13:39:53.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-02-25T22:55:10.551Z","etag":null,"topics":["barcode","nodejs","validation"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orca-scan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-08T19:41:25.000Z","updated_at":"2022-05-01T15:54:43.000Z","dependencies_parsed_at":"2022-09-12T15:01:50.375Z","dependency_job_id":null,"html_url":"https://github.com/orca-scan/orca-validation-node","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Forca-validation-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Forca-validation-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Forca-validation-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orca-scan%2Forca-validation-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orca-scan","download_url":"https://codeload.github.com/orca-scan/orca-validation-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240779712,"owners_count":19856239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["barcode","nodejs","validation"],"created_at":"2024-11-11T01:18:58.905Z","updated_at":"2026-05-17T14:36:33.802Z","avatar_url":"https://github.com/orca-scan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# orca-validation-node\n\nThis is a working example of how to build a [Validation URL](https://orcascan.com/guides/barcode-scan-validation-webhook-56928ff9) for [Orca Scan](https://orcascan.com) using Node.js and Express.\n\n**Why?** when someone scans a barcode in the Orca Scan app, you might want to check the data **before** it gets saved. A Validation URL lets you:\n\n- **Reject bad data** - block a scan if a value is missing, out of range, or a duplicate\n- **Modify data** - auto-format, trim, or fill in fields before saving\n- **Guide the user** - show a success, warning, or error message right in the app\n\n## How it works\n\nWhen a user scans a barcode or edits a field, the app sends the row data to your server as a POST request:\n\n```json\n{\n    \"___orca_sheet_name\": \"Vehicle Checks\",\n    \"___orca_user_email\": \"user@example.com\",\n    \"___orca_row_id\": \"abc123\",\n    \"Barcode\": \"orca-scan-test\",\n    \"Name\": \"Orca Scan\"\n}\n```\n\nFields starting with `___` are Orca system fields. Everything else matches your sheet column names exactly _(case and spaces matter)_.\n\nYour server responds to tell Orca Scan what to do:\n\n| Response                          | What happens                                                 |\n|:----------------------------------|:-------------------------------------------------------------|\n| HTTP `204`                        | Allow - data saves as-is                                     |\n| HTTP `200` with fields            | Modify - Orca Scan updates the fields you return, then saves |\n| HTTP `400` with `___orca_message` | Reject - user sees an error and the save is blocked          |\n\n### In-app messages\n\nYou can show messages in the app by including `___orca_message` in your response:\n\n```json\n{\n    \"___orca_message\": {\n        \"display\": \"notification\",\n        \"type\": \"success\",\n        \"message\": \"Item verified\"\n    }\n}\n```\n\n| Property  | Options          | Effect                             |\n|:----------|:-----------------|:-----------------------------------|\n| `display` | `\"notification\"` | Brief banner at the top of the app |\n|           | `\"dialog\"`       | Popup the user must dismiss        |\n| `type`    | `\"success\"`      | Green                              |\n|           | `\"warning\"`      | Yellow                             |\n|           | `\"error\"`        | Red                                |\n\n\u003e Your server must respond within **750ms** or Orca Scan will ignore the response.\n\nSee [server.js](server.js) for working examples of all three response types, plus in-app notifications and secret verification.\n\n## Getting started\n\nYou'll need [Node.js](https://nodejs.org/) v11+ installed (`node -v` to check) and an [Orca Scan](https://orcascan.com) account.\n\n```bash\ngit clone https://github.com/orca-scan/orca-validation-node.git\ncd orca-validation-node\nnpm install\nnpm start\n```\n\nYour server is now running at `http://localhost:8888`.\n\n## Try it\n\nUse [cURL](https://curl.se) to send a test request from your terminal (just like Orca Scan would):\n\n```bash\ncurl -X POST http://localhost:8888 \\\n  -H 'Content-Type: application/json' \\\n  -H 'orca-sheet-name: Vehicle Checks' \\\n  -H 'orca-secret: your-secret-here' \\\n  -d '{\n    \"___orca_sheet_name\": \"Vehicle Checks\",\n    \"___orca_user_email\": \"user@example.com\",\n    \"___orca_row_id\": \"abc123\",\n    \"Barcode\": \"orca-scan-test\",\n    \"Name\": \"Orca Scan\"\n  }'\n```\n\n- **Name ≤ 20 chars** → empty `HTTP 204` response (data allowed)\n- **Name \u003e 20 chars** → `HTTP 400` with an error message (data rejected)\n\n## Connect to Orca Scan\n\nOrca Scan needs to reach your server over the internet. During development, [localtunnel](https://github.com/localtunnel/localtunnel) creates a temporary public URL that points to your laptop:\n\n```bash\nnpx localtunnel --port 8888\n```\n\nCopy the URL it gives you and paste it in Orca Scan under **Integrations \u003e Events API \u003e Validation URL**.\n\nWhen you're ready to go live, deploy to any Node.js host (e.g. [Railway](https://railway.app), [Render](https://render.com)) and update the URL.\n\n## Security\n\nSet a secret in Orca Scan (**Integrations \u003e Events API \u003e Secret**) and Orca Scan will send it as an `orca-secret` header with every request. Verify it on your server to make sure the request is genuine. See the commented example in [server.js](server.js).\n\n## Help\n\n[Chat to us live](https://orcascan.com/#chat) if you run into any issues.\n\n## Examples in other languages\n\n| Language | Repository                                                                    |\n|:---------|:------------------------------------------------------------------------------|\n| C#       | [orca-validation-dotnet](https://github.com/orca-scan/orca-validation-dotnet) |\n| Python   | [orca-validation-python](https://github.com/orca-scan/orca-validation-python) |\n| Go       | [orca-validation-go](https://github.com/orca-scan/orca-validation-go)         |\n| Java     | [orca-validation-java](https://github.com/orca-scan/orca-validation-java)     |\n| PHP      | [orca-validation-php](https://github.com/orca-scan/orca-validation-php)       |\n\n## License\n\n\u0026copy; Orca Scan, the [Barcode Scanner app for iOS and Android](https://orcascan.com)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forca-scan%2Forca-validation-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forca-scan%2Forca-validation-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forca-scan%2Forca-validation-node/lists"}