Agent skill
Morta Webhooks Skill
Receive and verify Morta webhooks. Use when setting up Morta webhook endpoints, debugging Morta-Signature verification, or handling Morta hub events like table.row_created, project.created, member.created, and process.response_submitted.
Install this skill
npx skills add hookdeck/webhook-skills --skill morta-webhooks
When to Use This Skill
- How do I receive Morta webhooks?
- How do I verify the
Morta-Signatureheader? - How do I handle
table.row_created,project.created, ormember.createdevents? - How do I read Morta's double-encoded
changefield? - 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_ (unset or 0 = off).
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/, examples/nextjs/, 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_ | 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_ | 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.
Environment Variables
MORTA_WEBHOOK_SECRET=your_hub_signing_secret # Hub > Settings > Secrets
MORTA_WEBHOOK_TOLERANCE_SECONDS=0 # Optional replay window; unset or 0 = off
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 morta --path /webhooks/morta
Reference Materials
- references/overview.md - Morta webhook concepts, events, payload envelope
- references/setup.md - Create a notification and find the signing secret
- references/verification.md - Signature verification details and gotchas