Webhooks

Setting one up

Open a project, go to Settings and find the Webhook card. It takes three answers, and a project has one webhook. Configuring it is the project owner's to do — it carries a credential, which puts it in the same bundle as the API keys rather than with the translations.

The two events

Two, and that is the whole list. Both go to the same URL, and the one that arrived is named in the X-Mergua-Event header as well as in the body.

There is no separate event for a key being created, updated or deleted, and none for a review being approved. Whatever happened, what your pipeline does next is the same thing — fetch the files again — so all of it arrives as translations.changed, with the counts saying how much moved and the status breakdown saying where the language now stands.

A merge fires both: branch.merged at once, because that is the moment a release pipeline is waiting for, and translations.changed for the target branch out of the normal window.

What arrives

A JSON body, and five headers with it. The body says what changed; it never says what the text now reads.

translations.changed

{
  "event": "translations.changed",
  "id": "8f2c1e40-5b7a-4c3d-9e21-6a1f0b8d4e77",
  "timestamp": "2026-08-31T10:30:00.000Z",
  "project": { "id": "…", "slug": "acme-web", "name": "Acme Web" },
  "branch": "main",
  "locale": "de",
  "namespace": "common",
  "counts": { "added": 12, "updated": 3, "deleted": 0 },
  "statuses": { "DRAFT": 4, "TRANSLATED": 11, "REVIEWED": 0 },
  "keys": ["common.save", "common.cancel"],
  "keysTruncated": false
}

One delivery covers one language and one JSON file on one branch. A project holding three files, all of them touched by a single import, produces three deliveries — one per file — because that is the unit you would pull.

counts covers every change in the window. statuses is a headcount over the keys the payload names, read at the moment of sending rather than added up as the writes arrived — so it describes the state you will find when you pull, which is the only state you can act on. keys stops at 500 names and sets keysTruncated; the counts still describe everything that changed.

branch.merged

{
  "event": "branch.merged",
  "id": "1d9b7c22-3e44-4f10-8a6c-5b2e9f7a0c31",
  "timestamp": "2026-08-31T10:31:12.000Z",
  "project": { "id": "…", "slug": "acme-web", "name": "Acme Web" },
  "branch": "feature-checkout",
  "target": "main",
  "counts": { "added": 40, "updated": 8, "deleted": 1 }
}

branch is the branch that was merged, target where it went. This one does not wait for a window — it goes out as the merge completes.

One delivery, not four hundred

Almost nothing in Mergua writes a single cell. An import writes a whole file, an AI round fills a whole language, a bulk approval moves hundreds of rows at once. An event per key would mean an import of 400 keys arriving as 400 POSTs, so translations.changed is collected first and sent once.

The window is 60 seconds and it starts at the first change. It does not slide: further edits flow into the same delivery — counts add up, key names join the list — but they do not push the deadline back. A sliding window would starve a project somebody is actively working in, and you would hear nothing for as long as the work went on.

Two consequences worth designing for. A delivery arrives up to about a minute after the change, so do not treat the timestamp as the moment of the edit. And a pipeline triggered by this will sometimes run twice for one working session — make the run idempotent, which for "pull the files and commit if anything differs" it already is.

branch.merged is not collected. A merge is a named event with an obvious trigger, and a minute of latency there would be the whole cost of having the webhook at all.

Verifying the signature

Every delivery carries X-Mergua-Signature, which is sha256= followed by the hex HMAC-SHA256 of the request body under your signing secret. Your endpoint is a public URL, so check it before you act on anything.

Node

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = process.env.MERGUA_WEBHOOK_SECRET;
const app = express();

// express.raw, not express.json: the signature covers the bytes as sent.
app.post('/hooks/mergua', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Mergua-Signature') ?? '';
  const expected = 'sha256=' + createHmac('sha256', SECRET).update(req.body).digest('hex');

  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !timingSafeEqual(a, b)) {
    return res.status(401).send('bad signature');
  }

  const delivery = JSON.parse(req.body.toString('utf8'));

  // alreadyProcessed and enqueuePull are yours — see "Handling repeats" below.
  if (alreadyProcessed(delivery.id)) return res.status(200).send('ok');

  // Answer first, work afterwards: Mergua gives up after 10 seconds.
  res.status(200).send('ok');
  enqueuePull(delivery);
});

app.listen(3000);

timingSafeEqual rather than ===: a comparison that returns early leaks how much of a guess was right. It throws on a length mismatch, which is why the lengths are checked first.

Shell

For a receiver that is a CI job reading the body off a file:

# body.json holds the raw request body, exactly as received.
SIGNATURE=$(openssl dgst -sha256 -hmac "$MERGUA_WEBHOOK_SECRET" -hex < body.json \
  | sed 's/^.*= //')

if [ "sha256=$SIGNATURE" = "$HTTP_X_MERGUA_SIGNATURE" ]; then
  echo "signature ok"
else
  echo "signature mismatch" >&2
  exit 1
fi

Handling repeats

Every delivery has an id — a UUID, in the body and in the X-Mergua-Delivery header. It identifies the delivery, not the change, and it stays the same if the same delivery ever reaches you twice. Record the ones you have processed and drop a repeat.

A short-lived store is enough — a Redis key with a day's expiry, or a table you prune. You are guarding against a duplicate that arrives seconds apart, not against one from last month.

Two deliveries about the same file are not repeats. Edit a language now and again in ten minutes and you get two windows, two ids and two deliveries, and both are real. That is why the check is on the id rather than on branch, locale and namespace.

What to answer

Answer 2xx, and answer it quickly. Mergua gives up after 10 seconds and reads anything from 300 upwards as a failure — redirects included, since they are not followed. Verify the signature, put the work on a queue, return 200; do not pull and commit inside the request.

Which receivers work

One rule decides this, and it is worth knowing before you paste a URL in. Mergua sends fixed headers — content type, user agent and the three X-Mergua-* ones — and the body is always Mergua's own JSON. There is no Authorization header to set, and no way to change the shape of the body.

For the second group, put a small relay in front. Point Mergua at a catch-all URL from Zapier, Make or n8n — all three accept arbitrary JSON — and build the step that turns it into whatever the destination wants. No code, and about a quarter of an hour. A Cloudflare Worker or a Lambda does the same job if you would rather own it.

You rarely have to build that step more than once. Mattermost's incoming webhooks read Slack's payload format, and Discord's do too if you append /slack to the webhook URL — so one Slack-shaped message covers all three destinations.

Verify the signature in the relay, not after it: your relay is the public URL now, and it is the one thing holding the secret.

Worth knowing what such a message can say, before you build it. The payload carries no translations, so a chat notification comes out as "12 keys changed in de/common" plus a link into the project. That is the honest ceiling.