Quick start
- Get a key. The restaurant owner opens Settings → API & connected apps in OneBuzz, makes a key and gives it to you. It starts with
ob_live_ and is shown once.
- Check it.
curl https://onebuzzfood.com/api/v1/me -H "Authorization: Bearer $ONEBUZZ_KEY"
- Make an order. Item ids come from
GET /menu. Prices always come from the OneBuzz menu, never from your request.curl -X POST https://onebuzzfood.com/api/v1/orders \
-H "Authorization: Bearer $ONEBUZZ_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id":"kiosk-2026-000187","customer_name":"Aman","payment_mode":"CARD","items":[{"item_id":12,"qty":2,"variant":"Large"},{"item_id":31,"qty":1}]}'
- Give the customer the buzzer. Show
order.buzzer.join_url as a QR code or send it to their phone.
- Buzz them. When the food is ready:
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/ready -H "Authorization: Bearer $ONEBUZZ_KEY"
Every answer is JSON: {"success": true, "data": {…}}, or {"success": false, "error": {"code": "…", "message": "…"}} with a matching HTTP status. Times are UTC in ISO 8601. Money is a number in the restaurant's currency.
Keys & permissions
Send the key in the Authorization: Bearer header (or X-API-Key) over https. Call the API from your server, never from a web page or a phone app, because anyone could read the key there. A key works for one restaurant and can be tied to one outlet. The owner can remove it at any time.
| Permission | What it allows |
orders:read | See orders and buzzers |
orders:write | Make orders and buzzers, mark them preparing, ready, delivered or cancelled |
menu:read | See the menu |
menu:write | Mark menu items available or sold out |
sales:read | See sales totals |
tables:read | See tables and what is running on them |
staff:read | See the team and their login hours |
webhooks:write | Add and remove webhooks |
Restaurant
Who the key belongs to and its outlets.
GET/api/v1/me
This key. The restaurant, what the key may do and its outlets. A good first call to check a key.
Works with any key
Example
curl https://onebuzzfood.com/api/v1/me \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"restaurant": {
"id": 7,
"name": "Pizza Point",
"currency": "$",
"tax_label": "GST",
"tax_percent": 5,
"tax_included": false
},
"key": {
"id": 4,
"name": "Kiosk",
"scopes": [
"orders:read",
"orders:write",
"menu:read"
],
"location_id": null,
"created_at": "2026-11-12T09:00:00Z"
},
"locations": [
{
"id": 3,
"name": "Main counter",
"address": null,
"city": "Ludhiana",
"country": "IN",
"timezone": "Asia/Kolkata",
"pickup_point": "Counter 1",
"buzzer_on_every_order": true
}
],
"rate_limit": {
"requests_per_minute": 120
}
}
}
GET/api/v1/locations
Outlets. The outlets this key can use.
Works with any key
Example
curl https://onebuzzfood.com/api/v1/locations \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"locations": [
{
"id": 3,
"name": "Main counter",
"address": null,
"city": "Ludhiana",
"country": "IN",
"timezone": "Asia/Kolkata",
"pickup_point": "Counter 1",
"buzzer_on_every_order": true
}
]
}
}
Orders & buzzers
An order is a buzzer, a bill, or both. Its status goes WAITING → PREPARING → READY → DELIVERED, or CANCELLED.
GET/api/v1/orders
List orders. Newest first. Without dates you get today. status=active gives every order still running, whatever the day.
Needs orders:read
Query
location_id | integer | The outlet. Needed only when the restaurant has more than one and the key is not tied to one. |
status | string | active, waiting, preparing, ready, delivered or cancelled. |
from | date | First day, YYYY-MM-DD, in the outlet's time zone. |
to | date | Last day, YYYY-MM-DD. At most 92 days in one call. |
external_id | string | Find the order you made with this external_id. |
limit | integer | 1 to 100. Default 50. |
before_id | integer | For the next page: the next_before_id of the last answer. |
Example
curl https://onebuzzfood.com/api/v1/orders \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"orders": [
{
"id": 48213,
"code": "104",
"status": "WAITING",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
}
],
"has_more": false,
"next_before_id": null,
"filters": {
"status": null,
"from": "2026-11-30",
"to": "2026-11-30",
"limit": 50
}
}
}
GET/api/v1/orders/{id}
One order. The order with its bill, items and, while the buzzer is active, the customer's buzzer link.
Needs orders:read
Example
curl https://onebuzzfood.com/api/v1/orders/48213 \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "WAITING",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
}
}
}
POST/api/v1/orders
Make an order. With "items" it makes a bill (prices always come from the OneBuzz menu) and, unless the outlet has buzzers off, a buzzer. Without "items" it makes a buzzer only. Show buzzer.join_url as a QR or send it to the customer: their phone rings when the order is ready. Send your own order id as external_id (or an Idempotency-Key header) and a repeated call returns the same order with "duplicate": true.
Needs orders:write
Body (JSON)
location_id | integer | The outlet. Needed only when the restaurant has more than one and the key is not tied to one. |
items | array | The lines: {"item_id", "qty", "variant" (size name, when the item has sizes), "note", "addons": [{"g": add-on group id, "n": option name}]}. |
external_id | string | Your own id for this order, at most 80 characters. Makes the call safe to repeat. |
customer_name | string | Shown on the Live board and the bill. |
customer_phone | string | Digits only. Also used for loyalty points when the restaurant has them on. |
order_type | string | TAKEAWAY (default), DINE_IN or DELIVERY. |
table_no | string | For DINE_IN. |
payment_mode | string | UNPAID (default: the counter collects), CASH or CARD when you already took the money (UPI too for restaurants in India). |
discount | number | An amount taken off the bill. |
buzzer | boolean | true or false to decide it yourself; leave it out to follow the outlet's setting. |
notes | string | Only for a buzzer without items. |
Example
curl -X POST https://onebuzzfood.com/api/v1/orders \
-H "Authorization: Bearer $ONEBUZZ_KEY" \
-H "Content-Type: application/json" \
-d '{"external_id":"kiosk-2026-000187","customer_name":"Aman","payment_mode":"CARD","items":[{"item_id":12,"qty":2,"variant":"Large"},{"item_id":31,"qty":1}]}'
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "WAITING",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
},
"duplicate": false
}
}
POST/api/v1/orders/{id}/preparing
Mark preparing. The kitchen started. Only a WAITING order can move here.
Needs orders:write
Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/preparing \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "PREPARING",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": "2026-11-30T07:43:00Z",
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
},
"changed": true
}
}
POST/api/v1/orders/{id}/ready
Mark ready (buzz). The order is ready. The customer's phone rings. "changed" is false when it was ready already, so a repeated call never buzzes twice.
Needs orders:write
Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/ready \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "READY",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 1,
"customer": {
"connected": true,
"response": "ALERTING",
"response_at": "2026-11-30T07:52:40Z"
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": "2026-11-30T07:52:40Z",
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
},
"changed": true,
"alert": {
"phones": 1,
"sent": 1
}
}
}
POST/api/v1/orders/{id}/buzz
Buzz again. Rings the customer once more. Only for a READY order with a buzzer.
Needs orders:write
Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/buzz \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "READY",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 2,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": {
"join_url": "https://onebuzzfood.com/customer/join.php?t=…",
"join_code": "482913"
}
},
"changed": true,
"alert": {
"phones": 1,
"sent": 1
}
}
}
POST/api/v1/orders/{id}/delivered
Mark delivered. The customer has the order. It leaves the Live board and the buzzer link stops working.
Needs orders:write
Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/delivered \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "DELIVERED",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": "2026-11-30T07:55:02Z",
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": null
},
"changed": true
}
}
POST/api/v1/orders/{id}/cancel
Cancel. Cancels an order that is not delivered yet. Its bill no longer counts as a sale, and stock and loyalty points go back.
Needs orders:write
Example
curl -X POST https://onebuzzfood.com/api/v1/orders/48213/cancel \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "CANCELLED",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 0,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": "2026-11-30T07:45:10Z",
"updated_at": "2026-11-30T07:41:12Z",
"buzzer": null
},
"changed": true
}
}
Tables
The tables of an outlet and what is running on them.
GET/api/v1/tables
Tables. Each table is FREE, HELD (an order is held on it, not billed yet) or RUNNING (a saved order is still open).
Needs tables:read
Query
location_id | integer | The outlet. Needed only when the restaurant has more than one and the key is not tied to one. |
Example
curl https://onebuzzfood.com/api/v1/tables \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"location_id": 3,
"enabled": true,
"tables": [
{
"id": 1,
"name": "1",
"state": "FREE",
"held": null,
"running": null
},
{
"id": 2,
"name": "2",
"state": "RUNNING",
"held": null,
"running": {
"order_id": 48213,
"code": "104",
"status": "PREPARING",
"total": 1006,
"due": 0
}
}
]
}
}
Sales
Totals for a range of days. Cancelled orders are left out.
GET/api/v1/sales/summary
Sales summary. Bills, sales, tax, what is still unpaid, the split by payment and order type, each day and the 50 most sold items. Old months that were moved into a sales file are no longer counted.
Needs sales:read
Query
location_id | integer | The outlet. Needed only when the restaurant has more than one and the key is not tied to one. |
from | date | First day, YYYY-MM-DD. Default today. |
to | date | Last day. At most 92 days in one call. |
Example
curl https://onebuzzfood.com/api/v1/sales/summary \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"from": "2026-11-01",
"to": "2026-11-30",
"timezone": "Asia/Kolkata",
"location_id": null,
"currency": "$",
"bills": 1840,
"sales": 912450,
"tax": 43450,
"discount": 5200,
"unpaid": 1006,
"average_bill": 495.9,
"cancelled_orders": 12,
"by_payment": {
"CASH": 301200,
"CARD": 610250,
"UNPAID": 1000
},
"by_order_type": {
"TAKEAWAY": {
"bills": 1210,
"sales": 566100
},
"DINE_IN": {
"bills": 630,
"sales": 346350
}
},
"by_day": [
{
"date": "2026-11-01",
"bills": 58,
"sales": 28710
}
],
"top_items": [
{
"name": "Margherita",
"variant": "Large",
"qty": 412,
"sales": 184988
}
]
}
}
Staff
The team and their login hours. Read only. Pay and payslips are not in the API.
GET/api/v1/staff
The team. Owner, managers, staff and HR logins. Email addresses are not included.
Needs staff:read
Example
curl https://onebuzzfood.com/api/v1/staff \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"staff": [
{
"id": 21,
"name": "Simran",
"role": "manager",
"active": true,
"location_id": 3,
"last_login_at": "2026-11-30T03:02:11Z",
"created_at": "2026-08-02T10:00:00Z"
}
]
}
}
GET/api/v1/staff/hours
Login hours. How long each manager, staff member and HR login was signed in, with breaks taken out. In seconds. Owners are not timed.
Needs staff:read
Query
from | date | First day, YYYY-MM-DD. Default today. |
to | date | Last day. At most 62 days in one call. |
Example
curl https://onebuzzfood.com/api/v1/staff/hours \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"from": "2026-11-24",
"to": "2026-11-30",
"timezone": "Asia/Kolkata",
"staff": [
{
"id": 21,
"name": "Simran",
"role": "manager",
"signed_in_seconds": 151200,
"break_seconds": 9000,
"worked_seconds": 142200,
"days_worked": 6,
"signed_in_now": true,
"on_break": null,
"by_day": [
{
"date": "2026-11-24",
"worked_seconds": 24300
}
]
}
],
"total_worked_seconds": 142200
}
}
Webhooks
OneBuzz calls your address when an order changes.
GET/api/v1/webhooks
List webhooks. The restaurant's webhooks and the events that exist.
Needs webhooks:write
Example
curl https://onebuzzfood.com/api/v1/webhooks \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"webhooks": [
{
"id": 2,
"url": "https://example.com/onebuzz",
"events": [
"order.created",
"order.ready"
],
"location_id": null,
"status": "ACTIVE",
"last_status": 200,
"last_delivery_at": "2026-11-30T07:52:41Z",
"created_at": "2026-11-12T09:05:00Z"
}
],
"events": [
"order.created",
"order.updated",
"order.preparing",
"order.ready",
"order.buzzed",
"order.customer_coming",
"order.delivered",
"order.cancelled"
]
}
}
POST/api/v1/webhooks
Add a webhook. The answer has the signing secret. It is shown only this once. A restaurant can have 5 webhooks.
Needs webhooks:write
Body (JSON)
urlneeded | string | Your https address. |
events | array | The events you want. Leave it out for all of them. |
location_id | integer | Only this outlet's orders. Leave it out for every outlet. |
Example
curl -X POST https://onebuzzfood.com/api/v1/webhooks \
-H "Authorization: Bearer $ONEBUZZ_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/onebuzz","events":["order.created","order.ready"]}'
{
"success": true,
"data": {
"webhook": {
"id": 2,
"url": "https://example.com/onebuzz",
"events": [
"order.created",
"order.ready"
],
"location_id": null,
"status": "ACTIVE",
"last_status": null,
"last_delivery_at": null,
"created_at": "2026-11-12T09:05:00Z"
},
"secret": "whsec_…"
}
}
DELETE/api/v1/webhooks/{id}
Remove a webhook. Deliveries to it stop straight away.
Needs webhooks:write
Example
curl -X DELETE https://onebuzzfood.com/api/v1/webhooks/48213 \
-H "Authorization: Bearer $ONEBUZZ_KEY"
{
"success": true,
"data": {
"deleted": true,
"id": 2
}
}
Webhook events
OneBuzz sends a POST with JSON to your https address within a few seconds, whether the change was made through the API, on the POS or on the Live board. Answer with any 2xx status within 8 seconds. If you do not, the delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. A webhook that fails 20 deliveries in a row is switched off, and the owner can switch it on again.
| Event | When |
order.created | A new order or buzzer was made |
order.updated | Items were added or changed, or the bill was paid |
order.preparing | The kitchen started the order |
order.ready | The order is ready (the customer is buzzed) |
order.buzzed | The customer was buzzed again |
order.customer_coming | The customer tapped "I'm coming" |
order.delivered | The order was handed over |
order.cancelled | The order was cancelled |
What arrives
Headers: X-OneBuzz-Event, X-OneBuzz-Delivery (the same number on every retry, so you can skip one you already handled) and X-OneBuzz-Signature.
{
"id": "evt_5f2c9a1b7d3e4f6a8b0c1d2e",
"event": "order.ready",
"api_version": "v1",
"created_at": "2026-11-30T07:52:40Z",
"restaurant_id": 7,
"location_id": 3,
"data": {
"order": {
"id": 48213,
"code": "104",
"status": "READY",
"has_buzzer": true,
"location_id": 3,
"external_id": "kiosk-2026-000187",
"customer_name": "Aman",
"notes": "2× Margherita (Large), 1× Coke",
"order_type": "TAKEAWAY",
"table_no": null,
"customer_phone": null,
"buzz_count": 1,
"customer": {
"connected": false,
"response": "NONE",
"response_at": null
},
"bill": {
"id": 9917,
"bill_no": 2451,
"currency": "$",
"subtotal": 958,
"discount": 0,
"tax_percent": 5,
"tax_amount": 47.9,
"round_off": 0.1,
"total": 1006,
"payment_mode": "CARD",
"paid": 1006,
"due": 0,
"pay_state": "PAID",
"items": [
{
"item_id": 12,
"name": "Margherita",
"variant": "Large",
"type": "VEG",
"qty": 2,
"unit_price": 449,
"line_total": 898,
"note": null,
"addons": []
},
{
"item_id": 31,
"name": "Coke",
"variant": null,
"type": "VEG",
"qty": 1,
"unit_price": 60,
"line_total": 60,
"note": null,
"addons": []
}
]
},
"created_at": "2026-11-30T07:41:12Z",
"preparing_at": null,
"ready_at": null,
"delivered_at": null,
"cancelled_at": null,
"updated_at": "2026-11-30T07:41:12Z"
}
}
}
Check the signature
The header looks like t=1764489160,v1=…. v1 is the HMAC-SHA256 of t + "." + body with your webhook's secret. Refuse anything that does not match.
const crypto = require('crypto');
// rawBody: the request body exactly as it arrived (a string, before JSON.parse)
function isFromOneBuzz(rawBody, header, secret) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
if (!m) return false;
if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false; // older than 5 minutes
const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}
Errors & limits
Each key may make 120 requests a minute. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit you get 429 with a Retry-After header.
| Status | Code | Meaning |
| 401 | UNAUTHENTICATED | No API key was sent. |
| 401 | INVALID_API_KEY | The key is wrong or was removed. |
| 402 | SUBSCRIPTION_EXPIRED | The restaurant's OneBuzz plan has ended. |
| 403 | FORBIDDEN | The key does not have the permission (scope) this endpoint needs, or it is tied to another outlet. |
| 403 | API_NOT_ENABLED | The API is not switched on for this restaurant. |
| 404 | ORDER_NOT_FOUND | No such order in this restaurant. |
| 409 | INVALID_STATE | The order cannot take this step now, for example "ready" on a delivered order. |
| 422 | VALIDATION_ERROR | Something in the request is missing or wrong. The message says what. |
| 422 | ITEM_UNAVAILABLE | An item in the order is marked sold out. |
| 429 | RATE_LIMITED | Too many requests. Wait for the seconds in the Retry-After header. |
| 500 | SERVER_ERROR | Something went wrong on our side. Safe to try again. |
Questions, or need something the API does not do yet? Contact Onebuzz Food.