Guide to Morta Webhooks: Features and Best Practices
Morta is a data and document platform for construction projects. Teams keep project data in hubs made of tables and documents (called processes in the API), with comments, review threads, scripts and syncs to other systems. A hub's webhooks send each change to your endpoint, so a reporting warehouse, a document control system or an automation can react when a row is added, a column changes or a document response is submitted.
You'll see how Morta notifications are scoped, the shared envelope behind its 76 events, how to verify Morta-Signature, and what the 10-second acknowledgement window means for your receiver.
What are Morta webhooks?
In Morta, a webhook is a notification on a hub, set up under Hub > Settings > Webhooks. You choose one or more event types and can limit the notification to a single table or document. Morta then posts every matching event to your endpoint.
Morta signs every webhook by default with the hub's signing secret, so each hub you integrate has its own key. In code and in payloads, a hub is a "project", which is why hub events are named project.* and the hub ID appears as contextProjectId.
Morta webhook features
| Feature | Details |
|---|---|
| Signature | hex HMAC-SHA256 |
| Signature header | morta-signature |
| Body | JSON |
| Event routing | Body field event |
From Morta's webhook documentation:
- Signatures use
t=<timestamp>,v1=<hex>, an HMAC of the timestamp, a full stop and the JSON body. - Any
2xxacknowledges the webhook. - Any other status, or no answer within 10 seconds, marks the delivery as failed.
- Retries, a timestamp tolerance and source IPs aren't documented.
Events and payloads
Every event shares one envelope. Only event and context vary.
| Field | Description |
|---|---|
id | Unique public ID of the event (use it as the idempotency key) |
event | Event identifier in resource.verb form, e.g. table.row_created |
resourceId | Public ID of the primary resource (the hub ID for member.*; the table ID for table.view_*) |
change | A JSON-encoded string describing the diff, or null. Parse it a second time |
context | Object whose shape depends on the event (e.g. { "rows": [...] }) |
user | User that triggered the event, or null for system events |
createdAt | UTC timestamp the event was generated |
contextProjectId | Hub ID |
contextProcessId, contextProcessSectionId, contextProcessResponseId | Related document, section, response IDs, or null |
contextTableId, contextTableViewId, contextTableColumnId | Related table, view, column IDs, or null |
change needs particular care: it's a JSON-encoded string inside the JSON body, so parse it a second time. resourceId points to the event's primary resource, with nested events using the parent, so table.view_created carries the table ID and member.* events carry the hub ID.
| Event routing | Body field event |
Morta documents 76 events across hubs (project.*), members and policies, tables (table.* for rows, cells, columns, views, comments, threads, syncs, CSV uploads and script or join errors) and documents (process.* for sections, responses, exports, comments and threads). GET /v1/notifications/event-types returns the machine-readable list. user.* account events go only to the audit log and are never sent by webhook. Read events such as project.read and table.read are high volume, so subscribe to them only if you need them.
Morta's examples use placeholders such as "See the TableRow schema" in place of real objects, so check the API reference for the shape of each context. Morta's table.row_created example shows the envelope, with context.rows holding the new rows and change as an encoded string:
{
"id": "1df6bd8a-b8a3-49a2-b07b-0de3f3cecbed",
"event": "table.row_created",
"resourceId": "4e687ada-900a-4562-b493-6c6f67ffca6e",
"change": "{\"added\": 1}",
"context": { "rows": ["See the TableRow schema"] },
"user": "See the User schema",
"createdAt": "2020-08-27T14:20:28.405158",
"contextProjectId": "9f1c0e2a-1b2c-4d3e-8f4a-5b6c7d8e9f00",
"contextProcessId": null,
"contextProcessSectionId": null,
"contextProcessResponseId": null,
"contextTableId": "4e687ada-900a-4562-b493-6c6f67ffca6e",
"contextTableViewId": null,
"contextTableColumnId": null
}
Setting up Morta webhooks
- Open the hub and go to Hub > Settings > Secrets. Copy the signing secret and store it as
MORTA_SIGNING_SECRET. - Go to Hub > Settings > Webhooks and create a notification.
- Enter your endpoint URL, for example
https://example.com/webhooks/morta. - Choose the events, such as
table.row_created,table.row_updatedandprocess.response_, and optionally restrict the notification to one table or document.submitted - Save.
For Hookdeck, create a Morta source using the hub's secret and register the source URL as the endpoint. Use one source per hub, since each hub has its own secret. To test locally, run:
npx hookdeck-cli listen 3000 morta --path /webhooks/morta
Then add a row to a table covered by the notification.
Securing Morta webhooks
Split Morta-Signature into t and v1, build the message from t, a full stop and the raw body, compute a hex HMAC-SHA256 with the hub's secret, and compare it with v1 in constant time. Morta's signature guide walks through the same steps in Python.
Node.js verification
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['morta-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const parts = signature.split(',').map((part) => part.trim());
const times = parts.filter((part) => part.startsWith('t=')).map((part) => part.slice(2));
if (times.length !== 1 || !/^[0-9]+$/.test(times[0])) return false;
const message = Buffer.concat([Buffer.from(`${times[0]}.`, 'utf8'), rawBody]);
const candidates = parts.filter((part) => part.startsWith('v1=')).map((part) => part.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
Morta's docs set no time window for t, and this verifier doesn't add one.
The handler parses change defensively and stores the event by id:
const express = require('express');
const app = express();
function parseChange(change) {
if (typeof change !== 'string') return null;
try {
return JSON.parse(change);
} catch {
return null;
}
}
app.post('/webhooks/morta', express.raw({ type: '*/*' }), async (req, res) => {
const signingSecret = process.env.MORTA_SIGNING_SECRET;
if (!signingSecret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, signingSecret)) return res.sendStatus(401);
let event;
try {
event = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
try {
await saveMortaEvent(event.id, {
type: event.event,
hubId: event.contextProjectId,
tableId: event.contextTableId,
documentId: event.contextProcessId,
change: parseChange(event.change),
context: event.context,
});
} catch {
return res.sendStatus(503);
}
res.sendStatus(200);
});
saveMortaEvent ignores an id it has seen before. Syncing rows to a warehouse or starting a review happens afterwards, outside the 10-second window.
Hookdeck's Morta source checks the same timestamped HMAC with no age limit. It answers Morta with 200 and records a mismatch as failed verification.
Make Morta webhooks production-ready. Hookdeck Event Gateway acknowledges Morta well inside 10 seconds, keeps every table and document event, and retries your downstream systems on a schedule you control.
Morta webhook limitations and pain points
No documented retries
The Problem: You don't know whether a failed delivery is ever sent again.
Why It Happens: Morta documents the 10-second acknowledgement and that failures are marked failed, but not whether or when it retries.
Workarounds:
- Keep the endpoint fast and highly available.
- Reconcile rows and documents through the Morta API after an outage.
How Hookdeck Can Help: Hookdeck accepts each delivery and handles retries to your service itself, with replay for anything that still fails.
Read events can flood the endpoint
The Problem: Subscribing to *.read events produces far more traffic than writes.
Why It Happens: Every time someone opens a hub, table, view or document, a read event fires.
Workarounds:
- Subscribe only to the events you act on.
- Limit notifications to specific tables or documents.
How Hookdeck Can Help: Hookdeck filters can drop read events you don't need and route the rest, so your service only sees what matters.
change is a string inside JSON
The Problem: Code that treats change as an object fails.
Why It Happens: Morta encodes the diff as a JSON string, or sends null when there's no diff.
Workarounds:
- Parse it a second time with a guard, as in the example.
- Store the raw string alongside the parsed value for debugging.
How Hookdeck Can Help: A Hookdeck transformation can parse change into an object before delivery, so every consumer receives the same structure.
Examples use schema placeholders
The Problem: You can't see real context values in the documentation.
Why It Happens: Morta's examples replace objects with references such as "See the TableRow schema".
Workarounds:
- Use the API reference schemas for each
contexttype. - Capture a real delivery for each event before mapping fields.
How Hookdeck Can Help: Hookdeck stores each delivery in full, so you can browse real payloads per event type.
Best practices
One secret per hub
Each hub signs with its own secret. Use contextProjectId to pick the right key, or give each hub its own endpoint.
Deduplicate on id
Every event has a unique id. Keep it with a unique constraint, as described in implementing webhook idempotency.
Acknowledge within 10 seconds
Store the event and return 2xx, then sync or notify. Our asynchronous processing guide explains the pattern.
Watch error events
table.sync_error, table.script_error, table.join_error and the *.duplication_failed events report problems inside Morta. Routing them to an alerting channel catches broken automations early.
Conclusion
Morta webhooks report hub, table and document activity in one consistent envelope, signed with a timestamped HMAC-SHA256 in Morta-Signature. Verify the raw body with the hub's secret, parse change twice, deduplicate on id, and answer within 10 seconds, since Morta doesn't say whether failed deliveries come back.
Hookdeck Event Gateway gives Morta events a dependable path into your project systems.
Get started with Hookdeck for free and handle Morta webhooks reliably in minutes.