Guide to Katana MRP Webhooks: Features and Best Practices
Katana is a cloud manufacturing ERP for small and mid-sized makers: it tracks sales orders, purchasing, bills of materials, manufacturing orders and stock across products and raw materials. Its webhooks let an e-commerce store, a warehouse system or an accounting tool react when an order ships, a production run finishes or a material runs low, without polling Katana's API.
This guide covers creating Katana webhooks through the API, the event names (including a naming conflict on the billed events), working with Katana's thin payloads, verifying x-sha2-signature, and the 10-second acknowledgement window.
What are Katana MRP webhooks?
There's no webhook screen in the Katana app. You create a webhook by calling POST /v1/webhooks with a URL and a list of subscribed_events, and the response returns a signing token for that webhook alone.
A delivery tells you what happened and to which record, but not the record itself. The body names the resource_type and the action, and object carries only the record's id, status and an href to fetch it from the API. A receiver usually verifies, acknowledges, then loads the current record.
Every delivery is signed with HMAC-SHA256 over the raw body, and the hex digest arrives in x-sha2-signature.
Katana MRP webhook features
| Feature | Details |
|---|---|
| Configuration | API only: POST /v1/webhooks with url and subscribed_events |
| Signature | hex HMAC-SHA256 |
| Signature header | x-sha2-signature |
| Signed content | The raw request body |
| Key | The webhook's token, one per webhook |
| Body | JSON: resource_type, action, webhook_id, object |
| Event routing | Body field action |
| Acknowledgement | 20X within 10 seconds |
| Retries | 3 more attempts after 30 s, 2 min and 15 min (each "or more") |
| Retry header | x-katana-retry-num (1, 2 or 3) |
| HTTP method | Not documented |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
sales_order.created | A sales order is created | Sync new orders to a CRM or WMS |
sales_order.delivered | A sales order's status is marked DELIVERED | Send shipping confirmation |
sales_order.invoiced | An invoice is added to or removed from a sales order (one event per invoice) | Post to accounting |
purchase_order.received | A purchase order is marked RECEIVED | Update inbound stock |
purchase_ | A purchase order is marked PARTIALLY_RECEIVED | Track partial deliveries |
manufacturing_order.done | A manufacturing order is marked DONE | Update finished-goods inventory |
manufacturing_ | A manufacturing order is marked BLOCKED | Alert production |
current_ | A product's stock falls below its optimal level | Trigger reorder |
Documented event strings
sales_order.:created,updated,deleted,packed,delivered,invoiced,availability_updated,approvedpurchase_order.:created,updated,deleted,partially_received,received,approvedpurchase_order_row.:created,updated,deleted,receivedoutsourced_:purchase_ order. created,updated,deleted,received,approvedoutsourced_:purchase_ order_ row. created,updated,deleted,receivedoutsourced_:purchase_ order_ recipe_ row. created,updated,deletedmanufacturing_order.:created,updated,deleted,blocked,in_progress,donemanufacturing_:order_ operation_ row. created,updated,deleted,blocked,in_progress,paused,completedmanufacturing_:order_ recipe_ row. created,updated,deleted,ingredients_in_stockcurrent_inventory.:product_updated,material_updated,product_out_of_stock,material_out_of_stockproduct.,material.,variant.:created,updated,deletedproduct_recipe_row.:created,updated,deleted- Billed: Katana's events table names these
purchase_andorder_ row.billed outsourced_, while the create-webhookpurchase_ order_ recipe_ row.billed subscribed_eventsenum and the changelog that announced them usepurchase_order.billedandoutsourced_purchase_ order.billed
Subscribe using the enum spelling, and match both spellings in your router until a real delivery shows which one Katana sends.
Event Payload Structure
The body has four fields: resource_type, action (for example sales_order.delivered), webhook_id (typed as a number) and object. object holds only id, status and href, so fetch the full record from href with your API key. The invoiced and billed events add invoice_id or bill_id, integration_type and operation to object, but Katana shows no example of them. Its only payload example uses placeholders, so check field values against a real delivery.
Setting up Katana MRP webhooks
Prerequisites
- A Katana account with an API key (Bearer token)
- A public HTTPS endpoint (use
npx hookdeck-cli listen 3000 katana --path /webhooks/katanafor local development)
Create the Webhook and Get Your Signing Token
curl -X POST https://api.katanamrp.com/v1/webhooks \
-H "Authorization: Bearer $KATANA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/katana",
"subscribed_events": ["sales_order.created", "purchase_order.received", "manufacturing_order.done"]
}'
The response includes a token field (for example 73f82127d57a2cea). Store it as WEBHOOK_SECRET and use it as a UTF-8 string, even though it looks like hex.
Each webhook gets its own token. If several webhooks point at one URL, your receiver can't know which token signed a delivery without trying each, so give every webhook its own path or its own Hookdeck source.
HTTP Method
Katana's pages don't say which HTTP method delivers webhooks, and the documented example is printed oddly, under a 201 Created status line. The linked skill's examples therefore accept GET, POST, PUT, PATCH and DELETE, and this guide's handler uses app.all. Hookdeck's Katana MRP source (type KATANA) pre-selects POST without managing the method, so if Katana turns out to use another one, allow it on the source.
Subscribing Tips
- Subscribe only to the events a consumer needs. Each webhook can carry a different list.
- A status event and its update event (for example
sales_order.deliveredandsales_order.updated) can both fire for one change and deliver identical payloads. Subscribe to one, or deduplicate.
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
npx hookdeck-cli listen 3000 katana --path /webhooks/katana
Create a webhook with the CLI's URL, then change a test sales order's status. Note the method, x-sha2-signature and action on the first delivery.
Securing Katana MRP webhooks
Compute HMAC-SHA256 over the raw body with the webhook token as the key, hex-encode it, and compare it with x-sha2-signature in constant time. Katana warns that parsing the JSON first can reorder fields and break the match. See Verifying webhook signature.
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['x-sha2-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler below accepts any method, verifies, and loads the record from href for the actions it cares about.
const express = require('express');
function createKatanaApp({ fetchFromKatana, upsert, remove }) {
const app = express();
app.all('/webhooks/katana', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
if (!req.body.length) return res.sendStatus(200);
let parsed;
try {
parsed = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return res.sendStatus(400);
const { action, object } = parsed;
if (typeof action !== 'string' || !object || typeof object !== 'object') {
return res.sendStatus(400);
}
try {
if (action.endsWith('.deleted')) {
await remove(action.split('.')[0], object.id);
} else if (
action.startsWith('sales_order.') ||
action.startsWith('manufacturing_order.') ||
action.startsWith('current_inventory.')
) {
const record = await fetchFromKatana(object.href);
await upsert(action, record);
}
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
Fetching inside the request is fine for light traffic. With bursts of inventory updates, queue the body and fetch afterwards to stay within 10 seconds.
The signature covers only the body, with no timestamp, so a replayed request still verifies. Since each delivery points at the current record rather than carrying a snapshot, re-fetching from href makes most handlers safe to repeat.
When a Katana MRP source receives a request, Hookdeck checks x-sha2-signature against the raw body using the webhook token. Katana gets 200 either way; a failed check is recorded as failed verification and the request isn't forwarded. Hookdeck sets no timestamp tolerance for Katana.
Make Katana MRP webhooks production-ready. Hookdeck Event Gateway acknowledges Katana inside 10 seconds, verifies each token's signature, and keeps order and inventory events replayable well past Katana's final 15-minute retry.
Katana MRP webhook limitations and pain points
A short retry tail
The Problem: An outage of more than about 20 minutes loses order and stock events.
Why It Happens: After the first attempt, Katana tries three more times, at roughly 30 seconds, 2 minutes and 15 minutes. After that the event is gone.
Workarounds:
- Reconcile orders and stock levels through the API after any downtime.
- Alert when
x-katana-retry-numreaches 3, since that is the last attempt.
How Hookdeck Can Help: Hookdeck takes the delivery on Katana's first attempt and stores it, then retries your service on its own schedule.
Thin payloads
The Problem: Every event needs an API call before you can act on it, which adds latency and API usage.
Why It Happens: object holds only id, status and href.
Workarounds:
- Fetch from
hrefin a background worker, not in the request. - Use
statusalone where it's enough (for exampleDONEon a manufacturing order).
How Hookdeck Can Help: Hookdeck's delivery rate limits on a destination smooth bursts of events so the follow-up API calls don't spike.
Duplicate payloads for one change
The Problem: The same change triggers your logic twice.
Why It Happens: Katana notes that subscribing to both a status event and the matching update event can deliver two identical payloads.
Workarounds:
- Subscribe to the status events or the update events, not both, for a resource.
- Deduplicate on
action,object.idandobject.statuswithin a short window.
How Hookdeck Can Help: Hookdeck deduplication can drop identical payloads that arrive close together.
Undocumented method and billed-event names
The Problem: Requests are rejected for using an unexpected method, or billed events are never routed.
Why It Happens: The docs don't state the HTTP method, and the billed events are spelled two ways across Katana's pages.
Workarounds:
- Accept any method and verify the signature regardless.
- Match both billed spellings.
How Hookdeck Can Help: Hookdeck records the method and full body of every request, so the first real delivery settles both questions.
No dashboard for webhooks
The Problem: Nobody can see which webhooks exist or what they subscribe to without using the API.
Why It Happens: Webhooks are created and managed only through the API.
Workarounds:
- Keep webhook definitions in code or infrastructure configuration, with their tokens in a secret store.
- List webhooks through the API as part of a periodic audit.
How Hookdeck Can Help: A Hookdeck source per Katana webhook gives you a visible inventory of endpoints and their traffic.
Best practices
One webhook, one path, one token
Give each Katana webhook its own URL so the receiver always knows which token to use.
Acknowledge first
Return a 20X as soon as the request is verified and stored, then fetch and process. The asynchronous processing guide has the pattern.
Sync state, not deltas
Treat each delivery as a prompt to re-read the record. Applying the current state is naturally idempotent, which the webhook idempotency guide explains in more depth.
Don't depend on webhook_id's type
It's documented as a number. Compare it as a string if you use it to look up the token.
Conclusion
Katana's webhooks are API-managed notifications rather than full events: each tells you which record changed and where to fetch it. The signature is simple, but the short retry tail, the undocumented method and the duplicate status and update events all need handling in the receiver.
Hookdeck Event Gateway gives a Katana integration a durable buffer and a record of every request, which covers the gaps Katana's three retries leave.
Get started with Hookdeck for free and handle Katana MRP webhooks reliably in minutes.