# 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).

```javascript
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](https://hookdeck.com/docs/sources#custom-methods)), so any other method Katana uses must also be allowed on the source.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/katana-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/katana-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/katana-webhooks/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_order.partially_received` | Part of a purchase order is received |
| `manufacturing_order.done` | A manufacturing order is completed |
| `inventory.product_out_of_stock` | A product runs out of stock |

The handlers deal with these and log the rest. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/katana-webhooks/references/overview.md) for the full list.

## Environment Variables

```bash
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):

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/katana-webhooks/references/overview.md) - How Katana webhooks work, event types, payload shape
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/katana-webhooks/references/setup.md) - Create a webhook through the API and get its token
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/katana-webhooks/references/verification.md) - Signature details, gotchas, debugging failures
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/katana-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests