# 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](https://docs.morta.io/webhooks/events):

* Signatures use `t=<timestamp>,v1=<hex>`, an HMAC of the timestamp, a full stop and the JSON body.
* Any `2xx` acknowledges 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:

```json
{
  "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

1. Open the hub and go to **Hub > Settings > Secrets**. Copy the signing secret and store it as `MORTA_SIGNING_SECRET`.
2. Go to **Hub > Settings > Webhooks** and create a notification.
3. Enter your endpoint URL, for example `https://example.com/webhooks/morta`.
4. Choose the events, such as `table.row_created`, `table.row_updated` and `process.response_submitted`, and optionally restrict the notification to one table or document.
5. 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:

```bash
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](https://docs.morta.io/webhooks/signature) walks through the same steps in Python.

### Node.js verification

```javascript
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`:

```javascript
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](/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 `context` type.
* 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](/webhooks/guides/implement-webhook-idempotency).

### Acknowledge within 10 seconds

Store the event and return `2xx`, then sync or notify. [Our asynchronous processing guide](/webhooks/guides/why-implement-asynchronous-processing-webhooks) 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](https://hookdeck.com) gives Morta events a dependable path into your project systems.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Morta webhooks reliably in minutes.