Early access. Watch is open to a small group first, until our Meta app is live for everyone. Everything on this page works for them today.
Talk to usWatch Doc #25 Reviewed Oct 30, 2026
Watch: order webhook API
Send your store's orders to Anacoic from any backend: the endpoint, how to sign a request, the order fields, limits, responses and code samples.
The order webhook lets any backend send its orders to Anacoic. You create it from the site’s store step (Other: signed webhook), which gives you two things:
- the URL to send orders to, which looks like
https://hooks.anacoic.com/orders/<connection id>; - the signing secret, 64 characters, shown only once.
Keep the secret on your server. Never put it in a web page or an app.
The request
POST https://hooks.anacoic.com/orders/<connection id>
Content-Type: application/json
X-Anacoic-Signature: t=<unix time>,v1=<signature>
The body is either one order:
{ "order_id": "1001", "created_at": "2026-10-14T12:31:00Z", "value": "59.90", "currency": "EUR", "status": "paid" }
or a batch of orders:
{
"orders": [
{ "order_id": "1001", "created_at": "2026-10-14T12:31:00Z", "value": "59.90", "currency": "EUR", "status": "paid" },
{ "order_id": "1002", "created_at": "2026-10-14T13:05:00+02:00", "value": 120, "currency": "EUR", "status": "refunded" }
]
}
Send an order when it’s placed, and again whenever it changes (paid, refunded, cancelled). A change needs updated_at (see below).
Signing a request
- Take the current time as a Unix timestamp in seconds, for example
1760445060. - Join the timestamp, a full stop and the exact bytes of the body you’re about to send:
1760445060.{"order_id":"1001",...}. - Compute the HMAC-SHA256 of that text, using the signing secret as the key, exactly as we showed it (the 64 characters as text). Write the result as hex.
- Send it in the header:
X-Anacoic-Signature: t=1760445060,v1=<hex>.
We check the signature over the raw body before reading anything else, so sign the body exactly as it goes over the wire. Re-encoding the JSON after signing (another library, different spacing) breaks the signature.
The timestamp must be within 300 seconds (5 minutes) of our clock, in either direction, so keep your server’s clock in sync. Older requests are refused, which stops anyone replaying one.
The header may carry up to five v1= values, which helps while you switch secrets; the request is accepted when one of them matches. With more than five, it is refused.
Order fields
Only these fields are read. Anything else in an order, such as a customer’s name or email, is dropped on arrival and never stored. Fields must be plain values: an object or a list in one of these fields is dropped too.
| Field | Required | Type | Notes |
|---|---|---|---|
order_id | Yes | string or number | Your order’s ID, up to 128 characters. Orders are matched by it, so a later delivery updates the same order. |
created_at | Yes | string | When the order was placed, ISO 8601 with a timezone: 2026-10-14T12:31:00Z or 2026-10-14T14:31:00+02:00. Without one, the order is rejected, because the day it belongs to would be a guess. |
value | Yes | number or string | The order total in the currency’s normal units: 59.9, "59.90", 120. A dot for decimals, no thousands separators. |
currency | Yes | string | A three-letter ISO 4217 code, such as EUR or usd. |
status | Yes | string | paid, pending, refunded or cancelled, in lower case. |
order_number | No | string or number | The number your team uses, up to 128 characters. |
updated_at | Needed for changes | string | When the order last changed, ISO 8601 with a timezone. It decides which version of an order wins: the newest updated_at is kept, whatever order deliveries arrive in. Without it (or without a timezone in it), a delivery only creates an order we don’t have yet and never changes a stored one, so a late retry of an older state can’t overwrite a newer one. Send it with every status change. |
source | No | string | web (the default), pos, draft, subscription, api or other. Anything else counts as other. Only web orders are compared with ad platforms (which orders count). |
test | No | boolean | true for a test order (the JSON value, not the text "true"). Test orders are never counted. |
Limits
- Body: up to 1 MB. A bigger body is refused with
413before anything is read. - Batch: up to 500 orders. A batch with more is refused as a whole with
413.
Within those limits, a full batch of 500 orders is fine, with every field filled in.
Responses
202 Accepted
The request was signed correctly and read. Each order was either accepted or rejected:
{
"accepted": 1,
"rejected": [
{ "index": 1, "error": "missing_or_invalid_created_at" }
]
}
index is the order’s position in your orders list, counting from 0 (a single order is index 0). Accepted orders are queued and appear in the site usually within a few minutes. Rejected ones are not stored; fix them and send them again.
When orders we already have arrive without updated_at, their changes are not applied (see updated_at above), and the answer says how many:
{
"accepted": 2,
"rejected": [],
"ignored_unversioned": 1,
"warnings": [{ "code": "unversioned_change_ignored", "orders": 1, "message": "…" }]
}
Send updated_at with every change and these fields don’t appear.
error | What to fix |
|---|---|
not_an_object | The entry isn’t a JSON object. |
missing_order_id | order_id is missing or empty. |
order_id_too_long, order_number_too_long | Longer than 128 characters. |
missing_or_invalid_created_at | created_at is missing, not a date, or has no timezone. |
invalid_status | status isn’t one of the four values. |
invalid_currency | currency isn’t a three-letter code. |
invalid_value | value is missing or not a plain number. |
event_id_too_long | The order ID makes the site’s event ID too long. Use a shorter ID. |
order_too_large | This one order is too big to queue on its own, even after we keep only the fields above. Check it for unusually long values. |
invalid_site_timezone | The site’s timezone setting is broken, so no order could be placed on a day. Check the site’s settings, or write to support. |
Other answers
| Status | Body | Meaning |
|---|---|---|
400 | Bad request | The body isn’t JSON, or isn’t an order or an orders list. |
401 | Unauthorized | The signature is missing, wrong or too old, or the webhook doesn’t exist or was disconnected. We give the same answer in every case. |
404 | Not found | The URL isn’t a webhook address. |
405 | Method not allowed | Use POST. |
413 | Payload too large or Too many orders in one batch (max 500) | See the limits above. |
503 | Service unavailable | Something on our side isn’t ready. Try again later. |
Retries
If you don’t get an answer, or you get a 503, send the same body again (with a new timestamp and signature). Retrying is safe: the same body is processed once, and orders are matched by order_id, so a repeat never adds a second order. With updated_at in each order, a retry that arrives after a newer change doesn’t undo it.
Code samples
Each sample reads the URL and the secret from the environment variables ANACOIC_WEBHOOK_URL and ANACOIC_WEBHOOK_SECRET.
Node.js (18 or later)
import crypto from "node:crypto";
const url = process.env.ANACOIC_WEBHOOK_URL; // https://hooks.anacoic.com/orders/...
const secret = process.env.ANACOIC_WEBHOOK_SECRET;
const body = JSON.stringify({
orders: [
{
order_id: "1001",
order_number: "#1001",
created_at: "2026-10-14T12:31:00Z",
value: "59.90",
currency: "EUR",
status: "paid",
source: "web",
},
],
});
const timestamp = Math.floor(Date.now() / 1000);
const signature = crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Anacoic-Signature": `t=${timestamp},v1=${signature}`,
},
body,
});
console.log(response.status, await response.text());
Python 3
import hashlib
import hmac
import json
import os
import time
import urllib.error
import urllib.request
url = os.environ["ANACOIC_WEBHOOK_URL"] # https://hooks.anacoic.com/orders/...
secret = os.environ["ANACOIC_WEBHOOK_SECRET"]
body = json.dumps({
"orders": [
{
"order_id": "1001",
"order_number": "#1001",
"created_at": "2026-10-14T12:31:00Z",
"value": "59.90",
"currency": "EUR",
"status": "paid",
"source": "web",
}
]
}).encode("utf-8")
timestamp = str(int(time.time()))
signature = hmac.new(secret.encode("utf-8"), timestamp.encode("utf-8") + b"." + body, hashlib.sha256).hexdigest()
request = urllib.request.Request(
url,
data=body,
method="POST",
headers={
"Content-Type": "application/json",
"X-Anacoic-Signature": f"t={timestamp},v1={signature}",
},
)
try:
with urllib.request.urlopen(request) as response:
print(response.status, response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
print(error.code, error.read().decode("utf-8"))
curl
BODY='{"orders":[{"order_id":"1001","order_number":"#1001","created_at":"2026-10-14T12:31:00Z","value":"59.90","currency":"EUR","status":"paid","source":"web"}]}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$ANACOIC_WEBHOOK_SECRET" | awk '{print $NF}')
curl -sS -X POST "$ANACOIC_WEBHOOK_URL" \
-H "Content-Type: application/json" \
-H "X-Anacoic-Signature: t=$TIMESTAMP,v1=$SIGNATURE" \
--data-binary "$BODY"
Use --data-binary, not -d: it sends the body exactly as signed.
Rotating the secret
If the secret leaks or gets lost, choose Rotate the secret in the site’s store step and confirm. You get a new secret at once, and the old one stops working straight away, so update your server right after.