Webhooks

Quick start

1. Open your dashboard as the workspace admin (Studio plan required).
2. Find the Integrations card and click + Add endpoint.
3. Enter your HTTPS URL, pick the events you care about, save.
4. Copy the signing secret shown on screen — this is the only time it's displayed in full.
5. Click Send test event in the Deliveries drawer to verify your endpoint receives + verifies the signature.

Event types

Payload shape

Every event arrives as a JSON POST with this envelope:

{
  "type":       "task.updated",
  "eventId":    "task:abc123:2026-04-30T14:22:01.234Z",
  "tenantId":   "t-abcdef0123",
  "createdUtc": "2026-04-30T14:22:01.456Z",
  "data": {
    "task":   { /* current task fields */ },
    "before": { /* previous task fields, on update events */ }
  }
}

Field rules:

• type — one of the event types above.
• eventId — stable per write. Safe to use as a dedupe key.
• tenantId — your workspace ID. Always your own (events fan out per-tenant).
• createdUtc — ISO 8601, UTC, when we built the event.
• data — event-specific payload. Task and project objects mirror what you'd get back from the dashboard's API. Tenant IDs are stripped from the inner object since they're already on the envelope.

Headers

Verifying the signature

Always verify the signature before trusting an incoming webhook. Use a constant-time comparison.

Node.js

const crypto = require('crypto');

function verifyMomentumSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// In an Express handler — make sure to use express.raw() so rawBody is intact:
app.post('/momentum-webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ok = verifyMomentumSignature(
      req.body,
      req.header('X-Momentum-Signature'),
      process.env.MOMENTUM_WEBHOOK_SECRET);
    if (!ok) return res.status(401).send('bad signature');
    const event = JSON.parse(req.body.toString('utf8'));
    // ... handle event ...
    res.status(200).end();
  });

Python

import hashlib, hmac

def verify_momentum_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header:
        return False
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header, expected)

# Flask example:
@app.post("/momentum-webhook")
def handle():
    raw = request.get_data()
    if not verify_momentum_signature(
        raw,
        request.headers.get("X-Momentum-Signature", ""),
        os.environ["MOMENTUM_WEBHOOK_SECRET"]):
        return "bad signature", 401
    event = json.loads(raw)
    # ... handle event ...
    return "", 200

Retries

Your endpoint should respond with a 2xx status as fast as possible — ideally under a second. We give 10 seconds before timing out.

Anything that's not a 2xx counts as a failed delivery. Failed deliveries retry on this schedule:

• Attempt 2 — 30 seconds after attempt 1
• Attempt 3 — 2 minutes later
• Attempt 4 — 10 minutes later
• Attempt 5 — 1 hour later
• (After 5 total attempts the delivery is marked failed permanently.)

Each attempt reuses the same X-Momentum-Delivery header value. Use it for idempotency on your end — the same delivery may arrive more than once if your endpoint replied slowly the first time.

If you've fixed your endpoint and want to replay a failed delivery sooner, click Retry now in the Deliveries drawer on the dashboard.

Rotating your signing secret

Open the endpoint in the Integrations card and click Rotate secret. The new secret is shown once — copy it into your endpoint's environment first, then save. There's no overlap window: the very next delivery uses the new key.

Disabling vs deleting

• Disable (uncheck Enabled in the editor) pauses delivery without removing the endpoint or its history. Ideal when you're doing endpoint maintenance.
• Delete removes the subscription. In-flight retries for that endpoint will be marked failed.

Limits

• Up to 5 endpoint subscriptions per workspace.
• HTTPS only. HTTP, localhost, and private/internal IPs are rejected at create time.
• 10-second per-attempt timeout, 5-attempt cap.
• Response bodies over 1000 characters are truncated in the delivery log.

Need a hand?

Email Info@getmomentum.studio with the URL of your endpoint and we'll help debug.