# Morta Webhooks

## When to Use This Skill

* How do I receive Morta webhooks?
* How do I verify the `Morta-Signature` header?
* How do I handle `table.row_created`, `project.created`, or `member.created` events?
* How do I read Morta's double-encoded `change` field?
* Why is my Morta webhook signature verification failing?

## Verification (core)

Morta sends a `Morta-Signature` header of the form `t=<unix seconds>,v1=<hex>`. `v1` is the
lowercase hex HMAC-SHA256 of `"<t>.<raw body>"`, keyed with the hub signing secret
(Hub > Settings > Secrets) as UTF-8 text. Sign the `t` string exactly as sent, over the **raw body
bytes**. The header may carry several `v1` entries: accept any match and ignore other keys. Check
that `v1` is exactly 64 hex characters before comparing, and compare in constant time. The comparison
is case-insensitive (lowercase both sides).

Don't reject old timestamps by default: Hookdeck retries and replays resend the original `t`, so a
window would reject legitimate deliveries. A tolerance is opt-in via `MORTA_WEBHOOK_TOLERANCE_SECONDS`
(unset or `0` = off).

```javascript
const crypto = require('crypto');

function verifyMortaWebhook(rawBody, header, secret, toleranceSeconds = 0) {
  const pairs = (header || '').split(',').map((p) => {
    const i = p.indexOf('=');
    return i < 0 ? [p.trim(), ''] : [p.slice(0, i).trim(), p.slice(i + 1).trim()];
  });
  const t = pairs.find(([k]) => k === 't')?.[1]; // keep as a string
  const sigs = pairs.filter(([k, v]) => k === 'v1' && /^[0-9a-fA-F]{64}$/.test(v)).map(([, v]) => v.toLowerCase());
  if (!t || sigs.length === 0) return false;
  if (toleranceSeconds > 0 && (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds)) return false; // opt-in
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'));
  return sigs.some((sig) => crypto.timingSafeEqual(Buffer.from(sig), expected)); // equal length: 64 bytes
}

```

Morta has no verification SDK (its docs show a Python/Flask sample), so verification is manual in every
framework. Answer `401` for a missing, malformed, or mismatched signature. Parse the body only after
the check, and treat every field as untrusted. Read the raw body with `express.raw({ type: '*/*' })`
(Express), `await request.arrayBuffer()` (Next.js), or `await request.body()` (FastAPI).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/morta-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/morta-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/morta-webhooks/examples/fastapi/).

## Common Event Types

Every delivery is a `POST` with the same JSON envelope; dispatch on the `event` field (`resource.verb`).
`change` is a JSON-encoded **string**, so parse it a second time.

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `table.row_created` | Rows are added to a table | Sync new data downstream |
| `table.row_updated` | Table rows change | Keep a mirror up to date |
| `project.created` | A hub is created | Provision related resources |
| `project.duplication_failed` | A hub duplication job fails (`change` carries the error) | Alert an owner |
| `member.created` | A user is added to a hub | Onboarding automation |
| `process.response_submitted` | A document response is submitted | Start a review workflow |

Morta documents 76 event types across `project.*`, `member.*`, `policy.*`, `table.*` and `process.*`
(documents). The rest are listed in [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/morta-webhooks/references/overview.md).

## Environment Variables

```bash
MORTA_WEBHOOK_SECRET=your_hub_signing_secret   # Hub > Settings > Secrets
MORTA_WEBHOOK_TOLERANCE_SECONDS=0              # Optional replay window; unset or 0 = off

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 morta --path /webhooks/morta

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/morta-webhooks/references/overview.md) - Morta webhook concepts, events, payload envelope
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/morta-webhooks/references/setup.md) - Create a notification and find the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/morta-webhooks/references/verification.md) - Signature verification details and gotchas