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-signature header?
  • Why does my Katana webhook signature verification fail?
  • How do I handle sales_order.created, purchase_order.received or manufacturing_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 token as 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_digest on bytes, after a fullmatch on [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.

actionTriggered When
sales_order.createdA sales order is created
sales_order.deliveredA sales order is delivered
purchase_order.receivedA purchase order is fully received
purchase_order.partially_receivedPart of a purchase order is received
manufacturing_order.doneA manufacturing order is completed
inventory.product_out_of_stockA 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →