Agent skill
Katana Webhooks Skill
Receive and verify Katana MRP webhooks (cloud manufacturing ERP). Use when setting up a Katana webhook endpoint, verifying the x-sha2-signature header (HMAC-SHA256 of the raw body), debugging signature failures, or handling events such as sales_order.created, purchase_order.received and manufacturing_order.done.
Install this skill
npx skills add hookdeck/webhook-skills --skill katana-webhooks
Katana MRP (katanamrp.com) is a cloud manufacturing ERP. You register webhooks through the public API (POST /webhooks with url and subscribed_events), and each webhook gets its own signing token, returned in the token field of the create response. Every delivery carries an x-sha2-signature header: the lowercase hex HMAC-SHA256 of the raw request body, keyed with that token.
When to Use This Skill
- How do I receive Katana webhooks?
- How do I verify the Katana
x-sha2-signatureheader? - Why does my Katana webhook signature verification fail?
- How do I handle
sales_order.created,purchase_order.receivedormanufacturing_order.done? - Why did Katana deliver the same event twice?
Verification (core)
- Header:
x-sha2-signature, bare hex digest, no prefix (compare the whole value). - Signed message: the raw body bytes only. No timestamp, id or other header is signed.
- Key: the webhook's
tokenas UTF-8 bytes (it looks like hex, e.g.73f82127d57a2cea, but never hex-decode it).
const crypto = require('crypto');
function verifyKatanaSignature(rawBody, signature, secret = process.env.KATANA_WEBHOOK_SECRET) {
// rawBody is a Buffer of the exact bytes received (empty Buffer if there is no body)
if (!secret || typeof signature !== 'string' || !/^[0-9a-fA-F]{64}$/.test(signature)) return false;
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
const received = Buffer.from(signature.toLowerCase(), 'hex'); // safe: format validated above
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}
- Missing or empty header, malformed value or mismatch:
401. - Python:
hmac.compare_digeston bytes, after afullmatchon[0-9a-fA-F]{64}. - Read the body raw (
express.raw({ type: '*/*' }),await request.arrayBuffer(),await request.body()) and parse JSON only after the check. Re-serialised JSON can reorder fields and break the signature. - No timestamp is signed, so there is no replay window to check. Deduplicate on the event instead.
- The HTTP method is not documented. Katana's docs don't name it, so accept GET, POST, PUT, PATCH and DELETE, verify first for every method, and treat a missing body as empty bytes.
- Hookdeck: Hookdeck's Katana MRP source (type
KATANA) accepts only the methods you allow (custom methods), so any other method Katana uses must also be allowed on the source.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Common Event Types
Dispatch on the body's top-level action field (<resource>.<verb>); resource_type names the resource. No header names the event. object holds only id, status and href, so fetch the record from href.
action | Triggered When |
|---|---|
sales_order.created | A sales order is created |
sales_order.delivered | A sales order is delivered |
purchase_order.received | A purchase order is fully received |
purchase_ | Part of a purchase order is received |
manufacturing_order.done | A manufacturing order is completed |
inventory.product_ | A product runs out of stock |
The handlers deal with these and log the rest. See references/overview.md for the full list.
Environment Variables
KATANA_WEBHOOK_SECRET=73f82127d57a2cea # the webhook's `token` from the create-webhook response
Delivery and Retries
Acknowledge with a 20X within 10 seconds. Otherwise Katana retries three more times, after 30 s, 2 min and 15 min (each "or more"). Subscribing to both a status event and the matching update event (for example sales_order.delivered and sales_order.updated) can deliver two identical payloads, so make handlers idempotent.
Local Development
Katana can't reach localhost. Tunnel with the Hookdeck CLI (no account required):
npx hookdeck-cli listen 3000 katana --path /webhooks/katana
Use the printed URL as the webhook's url when you create it through the API.
Resources
- references/overview.md - How Katana webhooks work, event types, payload shape
- references/setup.md - Create a webhook through the API and get its token
- references/verification.md - Signature details, gotchas, debugging failures
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests