baselinker-webhooks
Receive BaseLinker (Base.com) webhooks. Use when building a BaseLinker order or warehouse callback receiver, because BaseLinker is not a normal webhook source: deliveries arrive as HTTP HEAD requests with NO body, the entire payload is in the query string (observed params: order_id, state), there is NO signature verification of any kind (no HMAC, no secret, no handshake), and your response must be a bare bodyless 200. Use when debugging an empty req.body, wiring app.head / an exported HEAD route handler / @app.head, or polling getJournalList for change tracking.
hookdeck · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add hookdeck/webhook-skills --skill baselinker-webhooks技能说明
name: baselinker-webhooks description: > Receive BaseLinker (Base.com) webhooks. Use when building a BaseLinker order or warehouse callback receiver, because BaseLinker is not a normal webhook source: deliveries arrive as HTTP HEAD requests with NO body, the entire payload is in the query string (observed params: order_id, state), there is NO signature verification of any kind (no HMAC, no secret, no handshake), and your response must be a bare bodyless 200. Use when debugging an empty req.body, wiring app.head / an exported HEAD route handler / @app.head, or polling getJournalList for change tracking. license: MIT metadata: author: hookdeck version: "0.1.0" repository: https://github.com/hookdeck/webhook-skills
BaseLinker Webhooks
BaseLinker (rebranded Base.com) is a Polish multichannel e-commerce platform — order management, warehouse/inventory, and integrations with marketplaces, stores and couriers.
This is not a normal webhook source. Three things make BaseLinker unlike every other provider in this repo, and all three must be reflected in your handler:
- The transport is HTTP
HEAD, notPOST. A HEAD request has no body by definition — readingreq.body/await request.json()yields nothing or throws. - The entire payload is in the query string. Read it from the parsed query params. Query values are always strings — coerce numerics explicitly.
- There is no signature verification. None. No HMAC, no signature header, no timestamp/replay check, no shared secret, no handshake or challenge step.
BaseLinker also publishes no webhook documentation at all. Its public API
(api.baselinker.com, ~195 methods over connector.php) is strictly
request/response, with change tracking done by polling (getJournalList,
getOrderReturnJournalList, getInventoryProductLogs). Neither the English nor
the Polish help centre documents an outbound webhook. Everything below about the
wire format is stated as observed, not documented — see
references/overview.md for exactly what was observed and
what was not.
When to Use This Skill
- How do I receive BaseLinker (Base.com) webhooks?
- Why is my BaseLinker webhook body empty / why does
req.bodyhave nothing in it? - How do I handle an HTTP HEAD webhook in Express, Next.js, or FastAPI?
- How do I read
order_idandstatefrom a BaseLinker callback? - How do I verify a BaseLinker webhook signature? (You cannot — there is none.)
- Is
X-BLTokena webhook signature? (No — it is the outbound API request header.) - How do I track BaseLinker order changes reliably? (Poll
getJournalList.)
Verification (core): there is none
BaseLinker provides no cryptographic authentication for these callbacks. There is nothing to verify with, so do not write an HMAC verifier, a signature header check, a timestamp/replay window, or a shared-secret comparison against something BaseLinker sends — none of those inputs exist. Inventing one produces a handler that silently rejects (or silently pretends to check) every delivery.
This is corroborated by Hookdeck's own API spec, where the Baselinker source's auth schema is empty:
// SourceConfigBaselinkerAuth
{ "properties": {}, "additionalProperties": false } // accepts no secret at all
Every HMAC-based source in that same spec carries a webhook_secret_key.
BaseLinker sits in the small cohort of zero-property auth schemas alongside AWS
SNS, Microsoft Graph, Microsoft SharePoint, Monday, Strava, Tikkie, Ethoca and
Zift. There is also no handshake/challenge/ack step: unlike Trello (which uses
HEAD as a verification probe), a BaseLinker HEAD request resolves no challenge
controller and goes straight to ingestion.
What to do instead — defence in depth, none of it provided by the platform:
- Endpoint-URL secrecy. Use a long, unguessable path
(
/webhooks/baselinker/8f3c…). Never log the full URL. - Network controls. TLS only; a WAF/rate limit in front; restrict by source IP if you can establish one for your account (BaseLinker publishes no allowlist).
- A token you append to the endpoint URL. Because you control the URL you
register, you can add your own query param —
?token=<random>— and compare it timing-safely. This is your secret round-tripped back to you, not a BaseLinker signature, and it is visible in the URL. The examples implement this optional check.
const crypto = require('crypto');
// OPTIONAL, and NOT a BaseLinker signature: a token you appended to the endpoint
// URL yourself, echoed back in the query string. BaseLinker signs nothing.
function verifyUrlToken(query, expected) {
if (!expected) return true; // not configured — nothing to check
const provided = query.token;
if (typeof provided !== 'string') return false;
const a = Buffer.from(provided), b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
The Payload: Query Params on a Bodyless HEAD
The only query params actually observed (in Hookdeck's Baselinker ingestion fixtures) are:
| Param | Observed example | Notes |
|---|---|---|
order_id | 42 | A string on the wire — coerce with Number(...) / int(...) |
state | packed | Opaque string. Not a documented enum, and not an event-type discriminator |
These are observed examples, not a documented or exhaustive parameter list.
Do not assume any param is present, do not invent additional param names, and do
not build a switch over a fixed set of state values as if it were an event
catalogue.
HEAD /webhooks/baselinker?order_id=42&state=packed HTTP/1.1
Host: your-app.example.com
Because the delivery carries no body, it
阅读完整来源 ↗