Webhook Notifications

Real-time HTTP POST notifications for integrity and alignment events. Pipe violations, drift alerts, conscience escalations, alignment traces, and billing events into PagerDuty, Slack, Datadog, or any HTTP endpoint. Instead of polling the API, configure webhook endpoints to receive events as they happen. Mnemom signs every payload with HMAC-SHA256 so your server can verify authenticity before acting on it. Mnemom emits two categories of webhook events:

Integrity Events (AIP) — per-turn checkpoint verdicts from the gateway (violations, drift, conscience)
Alignment Trace Events (AAP) — post-hoc trace analysis from the observer (verification, escalation, policy)

Both use the same registration endpoint and table. A single webhook endpoint can subscribe to events from both systems.

AIP Checkpoint ──→ Gateway  ──→ Signed POST (X-AIP-Signature) ──→ Your Endpoint
AAP Trace      ──→ Observer ──→ Signed POST (X-AAP-Signature) ──→ Your Endpoint
                                       │
                                       ├── PagerDuty
                                       ├── Slack
                                       ├── Datadog
                                       └── Custom handler

Webhook notifications are available on the Enterprise plan. Contact sales to enable this feature.

Quick start

Get your first webhook firing in under 5 minutes: 1. Create an endpoint in your organization settings, or via the API:

curl -X POST https://api.mnemom.ai/v1/orgs/{org_id}/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/mnemom",
    "description": "Production alerts",
    "event_types": ["integrity.violation", "sideband.drift.fired", "trace.failed"]
  }'

This example subscribes to AIP integrity violations, drift alerts, and AAP trace failures — all at one endpoint. 2. Copy the signing secret from the response — it’s shown only once:

{
  "endpoint_id": "whe-a1b2c3d4",
  "url": "https://your-server.com/webhooks/mnemom",
  "signing_secret": "a1b2c3d4e5f6...",
  "event_types": ["integrity.violation", "sideband.drift.fired"],
  "is_active": true
}

Copy the signing_secret immediately. It is not retrievable after creation. If you lose it, use the rotate secret endpoint to generate a new one.

3. Send a test event to verify connectivity:

curl -X POST https://api.mnemom.ai/v1/orgs/{org_id}/webhooks/whe-a1b2c3d4/test \
  -H "Authorization: Bearer $TOKEN"

4. Verify the signature on your server (see Signature Verification below).

Event catalog

Mnemom emits 28 event types across two systems: AIP (integrity checkpoints from the gateway) and AAP (alignment traces from the observer), plus platform events for drift, reputation, teams, and billing.

Integrity events (AIP)

These events fire from the gateway as it processes each request.

Event Type	Description	Trigger
`integrity.checkpoint`	An integrity checkpoint was recorded	Every stored AIP checkpoint
`integrity.violation`	A boundary violation was detected	Checkpoint verdict = `boundary_violation`
`sideband.drift.fired`	Behavioral drift detected in a session	3+ consecutive non-clear verdicts
`drift.resolved`	A drift alert was acknowledged	Org member acknowledges alert
`conscience.escalation`	Conscience value conflict during analysis	Checkpoint has conscience conflicts
`conscience.values_updated`	Org conscience values were modified	Create, update, delete, or mode change
`agent.paused`	Agent was paused (manually or by auto-containment)	Containment pause action
`agent.resumed`	Agent was resumed or reactivated	Containment resume/reactivate action
`agent.killed`	Agent was killed	Containment kill action

AIP webhook payloads are signed with X-AIP-Signature and include X-AIP-Version.

Alignment trace events (AAP)

These events fire from the observer after post-hoc trace analysis.

Event Type	Description	Trigger
`trace.created`	New alignment trace recorded	Every trace submitted to Supabase
`trace.verified`	Trace passed verification checks	`verification.verified === true`
`trace.failed`	Trace failed verification checks	`verification.verified === false`
`trace.escalation_required`	Escalation condition detected	`trace.escalation.required === true`
`policy.violation`	Policy evaluation resulted in denial	`policyResult.verdict === 'fail'`

AAP webhook payloads are signed with X-AAP-Signature and include X-AAP-Version. Use the trace.* wildcard to subscribe to all trace events, or * for everything.

A single registration can subscribe to both AIP and AAP events. For example, event_types: ["integrity.violation", "trace.failed"] will receive gateway violations and observer trace failures at the same endpoint. The signature header (X-AIP-Signature vs X-AAP-Signature) tells you which system sent the event.

Platform events

Event Type	Description	Trigger
`reputation.score_changed`	Reputation score changed significantly	Score changed by more than 10 points
`reputation.grade_changed`	Reputation letter grade changed	Grade transition (e.g., BBB to A)
`quota.warning`	Usage approaching plan limit (80%+)	Cron check on billing period
`quota.exceeded`	Usage has exceeded plan limit (100%+)	Cron check on billing period
`quota.risk_exceeded`	Risk usage exceeded plan limit	Risk engine billing check
`quota.risk_warning`	Risk usage approaching limit (80%+)	Risk engine billing check
`subscription.status_changed`	Subscription status changed	Plan upgrade, downgrade, or cancellation
`team.created`	Team was created	Team CRUD
`team.archived`	Team was archived	Team CRUD
`team.member_added`	Agent added to team	Roster change
`team.member_removed`	Agent removed from team	Roster change
`team.card_updated`	Team alignment card changed	Card update
`team_reputation.score_changed`	Team score changed significantly	Score delta > 10 points
`team_reputation.grade_changed`	Team letter grade changed	Grade transition
`quota.team_reputation_exceeded`	Team reputation usage exceeded plan limit	Cron billing check
`quota.team_reputation_warning`	Team reputation usage approaching limit (80%+)	Cron billing check

Subscribe to specific event types when creating an endpoint, or leave event_types empty to receive all events.

Payload envelope

Every webhook delivery uses the same envelope structure:

{
  "id": "evt-a1b2c3d4",
  "type": "integrity.violation",
  "created_at": "2026-02-17T14:30:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    // Event-specific payload (see examples below)
  }
}

Field	Type	Description
`id`	string	Unique event ID (`evt-xxxxxxxx`). Use for idempotency.
`type`	string	One of the 28 event types above
`created_at`	string	ISO 8601 timestamp
`account_id`	string	Billing account that owns the resource
`data`	object	Event-specific payload

Example payloads

integrity.violation

{
  "id": "evt-vl7k2m9x",
  "type": "integrity.violation",
  "created_at": "2026-02-17T14:30:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "checkpoint_id": "ic-abc12345",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "verdict": "boundary_violation",
    "concerns": [
      {
        "category": "autonomy_violation",
        "severity": "high",
        "description": "Agent attempted to bypass escalation trigger"
      }
    ],
    "reasoning_summary": "Agent's reasoning shows intent to take action outside defined autonomy envelope."
  }
}

integrity.checkpoint

{
  "id": "evt-cp3j8n2w",
  "type": "integrity.checkpoint",
  "created_at": "2026-02-17T14:30:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "checkpoint_id": "ic-ghi34567",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "verdict": "clear",
    "concerns": [],
    "reasoning_summary": "Agent reasoning is consistent with declared values and autonomy envelope."
  }
}

sideband.drift.fired

{
  "id": "evt-dr9p4k1q",
  "type": "sideband.drift.fired",
  "created_at": "2026-02-17T14:31:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "alert_id": "ida-drift-abc123",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "severity": "high",
    "drift_direction": "value_erosion",
    "sustained_checks": 7,
    "message": "Detected 7 consecutive non-clear verdicts in session sess-def67890"
  }
}

drift.resolved

{
  "id": "evt-rs2m7h5v",
  "type": "drift.resolved",
  "created_at": "2026-02-17T15:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "alert_id": "ida-drift-abc123",
    "org_id": "org-xyz98765",
    "acknowledged_by": "user-uuid-1234"
  }
}

conscience.escalation

{
  "id": "evt-ce6t3w8r",
  "type": "conscience.escalation",
  "created_at": "2026-02-17T14:30:05.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "checkpoint_id": "ic-jkl45678",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "conflicts": [
      {
        "value": "transparency",
        "description": "Agent reasoning conflicts with declared transparency commitment"
      }
    ],
    "verdict": "review_needed"
  }
}

quota.warning

{
  "id": "evt-qw1n5b9d",
  "type": "quota.warning",
  "created_at": "2026-02-17T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "usage_percent": 85,
    "checks_used": 12750,
    "checks_included": 15000
  }
}

quota.exceeded

{
  "id": "evt-qx4m8g2j",
  "type": "quota.exceeded",
  "created_at": "2026-02-17T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "usage_percent": 105,
    "checks_used": 15750,
    "checks_included": 15000
  }
}

subscription.status_changed

{
  "id": "evt-ss7k3p1w",
  "type": "subscription.status_changed",
  "created_at": "2026-02-17T10:15:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "status": "active",
    "previous_plan_id": "plan-team",
    "new_plan_id": "plan-enterprise",
    "cancel_at_period_end": false
  }
}

conscience.values_updated

{
  "id": "evt-cv2m8n4x",
  "type": "conscience.values_updated",
  "created_at": "2026-02-19T16:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "org_id": "org-abc123",
    "action": "create",
    "value_id": "cv-def45678",
    "actor": "user-xyz789"
  }
}

reputation.score_changed

{
  "id": "evt-rs4n8k2p",
  "type": "reputation.score_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "score_before": 770,
    "score_after": 782,
    "grade": "A",
    "components": {
      "integrity_ratio": 920,
      "compliance": 850,
      "drift_stability": 700,
      "trace_completeness": 650,
      "coherence_compatibility": 390
    }
  }
}

reputation.grade_changed

{
  "id": "evt-rg3k7m2x",
  "type": "reputation.grade_changed",
  "created_at": "2026-02-21T14:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "agent_id": "agent-xyz",
    "grade_before": "BBB",
    "grade_after": "A",
    "score": 702
  }
}

team.created

{
  "id": "evt-tc1m4k7x",
  "type": "team.created",
  "created_at": "2026-02-25T10:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "org_id": "org-xyz789",
    "name": "Support Pipeline Alpha",
    "member_count": 3,
    "agent_ids": ["agent-a", "agent-b", "agent-c"]
  }
}

team.archived

{
  "id": "evt-ta2n5j8w",
  "type": "team.archived",
  "created_at": "2026-02-25T12:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "org_id": "org-xyz789",
    "name": "Support Pipeline Alpha"
  }
}

team.member_added

{
  "id": "evt-ma3p6h9v",
  "type": "team.member_added",
  "created_at": "2026-02-25T10:15:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "agent_id": "agent-d",
    "actor_id": "user-xyz789",
    "member_count": 4
  }
}

team.member_removed

{
  "id": "evt-mr4q7g1u",
  "type": "team.member_removed",
  "created_at": "2026-02-25T11:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "agent_id": "agent-b",
    "actor_id": "user-xyz789",
    "member_count": 3
  }
}

team.card_updated

{
  "id": "evt-cu5r8f2t",
  "type": "team.card_updated",
  "created_at": "2026-02-25T10:30:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "card_id": "card-def456",
    "card_source": "auto_derived",
    "actor_id": "user-xyz789"
  }
}

team_reputation.score_changed

{
  "id": "evt-ts6s9e3r",
  "type": "team_reputation.score_changed",
  "created_at": "2026-02-25T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "score_before": 790,
    "score_after": 812,
    "grade": "AA",
    "components": {
      "coherence_history": 880,
      "member_quality": 790,
      "operational_record": 850,
      "structural_stability": 720,
      "assessment_density": 640
    }
  }
}

team_reputation.grade_changed

{
  "id": "evt-tg7t1d4q",
  "type": "team_reputation.grade_changed",
  "created_at": "2026-02-25T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "team_id": "team-abc123",
    "grade_before": "A",
    "grade_after": "AA",
    "score": 812
  }
}

quota.team_reputation_exceeded

{
  "id": "evt-qe8u2c5p",
  "type": "quota.team_reputation_exceeded",
  "created_at": "2026-02-25T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "usage_percent": 110,
    "computations_used": 220,
    "computations_included": 200
  }
}

quota.team_reputation_warning

{
  "id": "evt-qw9v3b6n",
  "type": "quota.team_reputation_warning",
  "created_at": "2026-02-25T06:00:00.000Z",
  "account_id": "ba-x1y2z3w4",
  "data": {
    "usage_percent": 85,
    "computations_used": 170,
    "computations_included": 200
  }
}

AAP trace event payloads

AAP trace events use a different payload structure from AIP events. The envelope includes event (most specific event type), all_events (all applicable types for this trace), and a trace object with verification and policy results.

trace.created

{
  "event": "trace.created",
  "all_events": ["trace.created"],
  "timestamp": "2026-03-03T14:30:00.000Z",
  "trace": {
    "trace_id": "tr-a1b2c3d4",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "decision": {
      "reasoning": "Agent selected the most transparent response option",
      "alternatives_count": 3
    },
    "verification": null,
    "escalation": null,
    "policy": null
  }
}

trace.verified

{
  "event": "trace.verified",
  "all_events": ["trace.created", "trace.verified"],
  "timestamp": "2026-03-03T14:30:01.000Z",
  "trace": {
    "trace_id": "tr-e5f6g7h8",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "decision": {
      "reasoning": "Agent reasoning aligns with declared values",
      "alternatives_count": 2
    },
    "verification": {
      "verified": true,
      "warnings": []
    },
    "escalation": null,
    "policy": null
  }
}

trace.failed

{
  "event": "trace.failed",
  "all_events": ["trace.created", "trace.failed"],
  "timestamp": "2026-03-03T14:30:02.000Z",
  "trace": {
    "trace_id": "tr-i9j0k1l2",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "decision": {
      "reasoning": "Agent bypassed transparency requirements",
      "alternatives_count": 4
    },
    "verification": {
      "verified": false,
      "warnings": [
        "Decision conflicts with alignment card boundary: transparency_commitment",
        "No escalation was triggered despite high-risk action"
      ]
    },
    "escalation": null,
    "policy": null
  }
}

trace.escalation_required

{
  "event": "trace.escalation_required",
  "all_events": ["trace.created", "trace.failed", "trace.escalation_required"],
  "timestamp": "2026-03-03T14:30:03.000Z",
  "trace": {
    "trace_id": "tr-m3n4o5p6",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "decision": {
      "reasoning": "Agent attempted action requiring human oversight",
      "alternatives_count": 2
    },
    "verification": {
      "verified": false,
      "warnings": ["Escalation trigger was not activated"]
    },
    "escalation": {
      "required": true,
      "reason": "Action exceeds autonomy envelope",
      "triggered": false
    },
    "policy": null
  }
}

policy.violation

{
  "event": "policy.violation",
  "all_events": ["trace.created", "trace.failed", "policy.violation"],
  "timestamp": "2026-03-03T14:30:04.000Z",
  "trace": {
    "trace_id": "tr-q7r8s9t0",
    "agent_id": "mnm-550e8400-e29b-41d4-a716-446655440000",
    "session_id": "sess-def67890",
    "decision": {
      "reasoning": "Agent invoked restricted tool without authorization",
      "alternatives_count": 1
    },
    "verification": {
      "verified": false,
      "warnings": ["Tool usage violates policy constraints"]
    },
    "escalation": null,
    "policy": {
      "verdict": "fail",
      "violations": 2,
      "warnings": 1
    }
  }
}

AAP events are signed with X-AAP-Signature (not X-AIP-Signature). The HMAC-SHA256 algorithm is identical — only the header name differs. Use the header name to distinguish which system sent the webhook.

Security

HMAC-SHA256 signing

Every webhook delivery includes three headers for signature verification:

Header	Description
`X-Webhook-Id`	Unique event ID (same as `payload.id`)
`X-Webhook-Timestamp`	Unix timestamp (seconds) when the payload was signed
`X-Webhook-Signature`	HMAC-SHA256 signature in format `v1={hex}`

The signature is computed over the string {timestamp}.{raw_body} using your endpoint’s signing secret as the HMAC key. This follows the Stripe webhook signing convention.

Replay protection

Always verify that the timestamp is within an acceptable window (recommended: 5 minutes) to prevent replay attacks. Reject any delivery where X-Webhook-Timestamp is more than 300 seconds from your server’s current time.

Constant-time comparison

Use a constant-time comparison function when verifying signatures to prevent timing attacks. All standard libraries provide one — see the verification examples below.

Signature verification

Verify webhook signatures in your endpoint handler to ensure payloads are authentic and untampered. Below are examples in four languages.

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(req, signingSecret) {
  const timestamp = req.headers['x-webhook-timestamp'];
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.rawBody; // Must be raw string, not parsed JSON

  // 1. Check timestamp freshness (5-minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
    throw new Error('Timestamp too old — possible replay attack');
  }

  // 2. Compute expected signature
  const signatureInput = `${timestamp}.${rawBody}`;
  const expected = 'v1=' + createHmac('sha256', signingSecret)
    .update(signatureInput)
    .digest('hex');

  // 3. Constant-time comparison
  if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    throw new Error('Invalid signature');
  }

  return JSON.parse(rawBody);
}

import hmac
import hashlib
import time
import json

def verify_webhook_signature(request, signing_secret):
    timestamp = request.headers['X-Webhook-Timestamp']
    signature = request.headers['X-Webhook-Signature']
    raw_body = request.get_data(as_text=True)

    # 1. Check timestamp freshness (5-minute tolerance)
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError('Timestamp too old — possible replay attack')

    # 2. Compute expected signature
    signature_input = f'{timestamp}.{raw_body}'
    expected = 'v1=' + hmac.new(
        signing_secret.encode(),
        signature_input.encode(),
        hashlib.sha256
    ).hexdigest()

    # 3. Constant-time comparison
    if not hmac.compare_digest(signature, expected):
        raise ValueError('Invalid signature')

    return json.loads(raw_body)

package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/hex"
	"fmt"
	"math"
	"strconv"
	"time"
)

func VerifyWebhookSignature(timestamp, signature, rawBody, signingSecret string) error {
	// 1. Check timestamp freshness (5-minute tolerance)
	ts, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return fmt.Errorf("invalid timestamp")
	}
	if math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return fmt.Errorf("timestamp too old")
	}

	// 2. Compute expected signature
	signatureInput := fmt.Sprintf("%s.%s", timestamp, rawBody)
	mac := hmac.New(sha256.New, []byte(signingSecret))
	mac.Write([]byte(signatureInput))
	expected := "v1=" + hex.EncodeToString(mac.Sum(nil))

	// 3. Constant-time comparison
	if subtle.ConstantTimeCompare([]byte(signature), []byte(expected)) != 1 {
		return fmt.Errorf("invalid signature")
	}

	return nil
}

require 'openssl'
require 'json'

def verify_webhook_signature(request, signing_secret)
  timestamp = request.env['HTTP_X_WEBHOOK_TIMESTAMP']
  signature = request.env['HTTP_X_WEBHOOK_SIGNATURE']
  raw_body = request.body.read

  # 1. Check timestamp freshness (5-minute tolerance)
  if (Time.now.to_i - timestamp.to_i).abs > 300
    raise 'Timestamp too old — possible replay attack'
  end

  # 2. Compute expected signature
  signature_input = "#{timestamp}.#{raw_body}"
  expected = 'v1=' + OpenSSL::HMAC.hexdigest(
    'sha256', signing_secret, signature_input
  )

  # 3. Constant-time comparison
  unless ActiveSupport::SecurityUtils.secure_compare(signature, expected)
    raise 'Invalid signature'
  end

  JSON.parse(raw_body)
end

Always verify signatures against the raw request body (the exact bytes received), not a re-serialized JSON object. JSON serialization can alter key ordering, whitespace, or Unicode escaping, which will cause signature mismatches.

Delivery & retries

First delivery

Mnemom attempts inline delivery immediately when an event is emitted. Most webhooks arrive within seconds of the triggering event. The first delivery attempt includes up to 4 rapid retries (at 1s, 5s, and 15s intervals). If all inline attempts fail, the event enters the dead-letter queue (DLQ) for persistent retry.

Retry schedule

Failed deliveries are retried in two phases: Phase 1: Inline (immediate)

Attempt	Delay	Cumulative
1 (initial)	Immediate	0s
2	1 second	1s
3	5 seconds	6s
4	15 seconds	21s

Phase 2: DLQ (persistent, exponential backoff)

Attempt	Delay	Cumulative
5	1 minute	~1m
6	5 minutes	~6m
7	30 minutes	~36m
8	2 hours	~2h 36m
9	6 hours	~8h 36m
10	24 hours	~32h 36m

After 10 total attempts, the delivery is marked as dead (permanently failed). Platform alerts fire when a delivery is dead-lettered. You can redeliver dead events manually via the API.

Permanent vs. retryable failures

Response	Behavior
2xx	Success. Delivery marked as `delivered`.
429	Rate limited. Retries with at least 60s backoff.
4xx (except 429)	Permanent failure. No retries. Fix your endpoint.
5xx	Retryable. Follows backoff schedule above.
Timeout (>10s)	Retryable. Your endpoint must respond within 10 seconds.

Auto-disable

If an endpoint accumulates 100 consecutive failures, it is automatically disabled. The account owner receives an email notification. To resume deliveries:

Fix the underlying issue with your endpoint
Re-enable the endpoint in organization settings (or via PATCH with is_active: true)
The failure counter resets when you re-enable

Idempotency

Use the id field in the payload envelope as an idempotency key. The same event may be delivered more than once (e.g., after a redeliver request). Your handler should deduplicate using the event ID.

Ordering

Webhook deliveries are best-effort ordered by creation time. Due to retries and network variance, events may arrive out of order. Use the created_at timestamp for ordering if your use case requires it.

Testing

Test delivery button

Every endpoint has a “Test” action that sends a synthetic webhook.test event with a test payload. Use this to verify connectivity and signature verification without triggering a real integrity event.

curl -X POST https://api.mnemom.ai/v1/orgs/{org_id}/webhooks/{endpoint_id}/test \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "success": true,
  "status": 200,
  "latency_ms": 145,
  "error": null
}

Development tools

For local development, use webhook.site or ngrok to expose a local endpoint:

# Start ngrok tunnel
ngrok http 3000

# Use the HTTPS URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/mnemom

Delivery log

View the delivery history for any endpoint to debug issues:

curl https://api.mnemom.ai/v1/orgs/{org_id}/webhooks/deliveries?endpoint_id=whe-a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Each delivery record includes: status, HTTP response code, attempt count, latency, and error details.

Redelivery

Redeliver a failed event to retry with the same payload:

curl -X POST https://api.mnemom.ai/v1/orgs/{org_id}/webhooks/deliveries/{delivery_id}/redeliver \
  -H "Authorization: Bearer $TOKEN"

Integration examples

PagerDuty

Route integrity violations to PagerDuty as incidents:

app.post('/webhooks/mnemom', (req, res) => {
  verify(req); // Verify signature first

  const event = req.body;

  if (event.type === 'integrity.violation') {
    fetch('https://events.pagerduty.com/v2/enqueue', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        routing_key: process.env.PAGERDUTY_ROUTING_KEY,
        event_action: 'trigger',
        payload: {
          summary: `Integrity violation: ${event.data.agent_id}`,
          severity: 'critical',
          source: 'mnemom',
          custom_details: event.data,
        },
      }),
    });
  }

  res.sendStatus(200);
});

Slack

Post alerts to a Slack channel via incoming webhook:

app.post('/webhooks/mnemom', (req, res) => {
  verify(req);

  const event = req.body;
  const emoji = {
    'integrity.violation': ':rotating_light:',
    'sideband.drift.fired': ':warning:',
    'conscience.escalation': ':brain:',
    'quota.warning': ':chart_with_upwards_trend:',
    'trace.failed': ':x:',
    'trace.escalation_required': ':exclamation:',
    'policy.violation': ':no_entry:',
  }[event.type] || ':bell:';

  fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `${emoji} *${event.type}*\n${JSON.stringify(event.data, null, 2)}`,
    }),
  });

  res.sendStatus(200);
});

Datadog

Send custom events to Datadog:

app.post('/webhooks/mnemom', (req, res) => {
  verify(req);

  const event = req.body;

  fetch(`https://api.datadoghq.com/api/v1/events`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'DD-API-KEY': process.env.DD_API_KEY,
    },
    body: JSON.stringify({
      title: `Mnemom: ${event.type}`,
      text: JSON.stringify(event.data),
      tags: [`event_type:${event.type}`, `account:${event.account_id}`],
      alert_type: event.type.includes('violation') ? 'error' : 'info',
    }),
  });

  res.sendStatus(200);
});

Troubleshooting

Signature mismatch

Ensure you’re verifying against the raw request body, not re-serialized JSON
Check that your signing secret is correct — it was only shown once at creation time. If lost, rotate the secret.
Verify the timestamp header is being read correctly (it’s in Unix seconds, not milliseconds)

HTTPS required

Webhook endpoints must use HTTPS. HTTP URLs are rejected at creation time. For local development, use ngrok or a similar tunneling tool.

Timeouts (>10 seconds)

Your endpoint must respond within 10 seconds. If processing takes longer, return 200 immediately and process the event asynchronously (e.g., via a background job queue).

4xx permanent failure

HTTP 4xx responses (except 429) are treated as permanent failures and are not retried. Common causes:

401/403 — Your auth middleware is blocking the request. Mnemom webhooks don’t include bearer tokens.
404 — The endpoint URL path is incorrect.
400 — Your request validation is rejecting the payload format.

Endpoint auto-disabled

After 100 consecutive delivery failures, the endpoint is automatically disabled. Fix the underlying issue, then re-enable the endpoint. The failure counter resets on re-enable.

Events not firing

Verify the endpoint is active (is_active: true)
Check that the event type is included in the endpoint’s event_types (or that event_types is empty for all events)
Confirm the triggering action occurred on an agent linked to an Enterprise billing account
Check the delivery log for failed attempts

FAQ

Are there rate limits on webhook deliveries?

Mnemom does not impose explicit rate limits on outbound deliveries. However, if your endpoint returns 429 (Too Many Requests), we respect that signal and back off for at least 60 seconds before retrying.

Are events delivered in order?

Events are delivered in best-effort order. Due to retries and network conditions, events may arrive out of order. Use the created_at field for sequencing.

What is the maximum payload size?

Webhook payloads are typically under 4 KB. The maximum payload size is 64 KB.

How do I rotate my signing secret?

Use the rotate secret endpoint: POST /v1/orgs/{org_id}/webhooks/{endpoint_id}/rotate-secret. The new secret is returned once. Update your verification code before new deliveries arrive.

Can I have multiple endpoints?

Yes, up to 5 endpoints per organization. Each endpoint can subscribe to different event types.

How long are delivery logs retained?

Delivery records are retained for 30 days. Older records are automatically purged.

What happens to events during endpoint downtime?

Events are queued and retried according to the backoff schedule. If your endpoint recovers within the retry window (~1 hour), all events will be delivered. Beyond that, they are marked as failed but remain in the delivery log for redelivery.

API reference

Endpoint	Description
POST /orgs//webhooks	Create webhook endpoint
GET /orgs//webhooks	List webhook endpoints
GET /orgs//webhooks/	Get endpoint details
PATCH /orgs//webhooks/	Update endpoint
DELETE /orgs//webhooks/	Delete endpoint
POST …/rotate-secret	Rotate signing secret
POST …/test	Send test delivery
GET …/deliveries	Delivery log
POST …/redeliver	Redeliver failed event

Guides

Safe House

Webhook Notifications

Quick start

Event catalog

Integrity events (AIP)

Alignment trace events (AAP)

Platform events

Payload envelope

Example payloads

AAP trace event payloads

Security

HMAC-SHA256 signing

Replay protection

Constant-time comparison

Signature verification

Delivery & retries

First delivery

Retry schedule

Permanent vs. retryable failures

Auto-disable

Idempotency

Ordering

Testing

Test delivery button

Development tools

Delivery log

Redelivery

Integration examples

PagerDuty

Slack

Datadog

Troubleshooting

FAQ

API reference

​Quick start

​Event catalog

​Integrity events (AIP)

​Alignment trace events (AAP)

​Platform events

​Payload envelope

​Example payloads

​AAP trace event payloads

​Security

​HMAC-SHA256 signing

​Replay protection

​Constant-time comparison

​Signature verification

​Delivery & retries

​First delivery

​Retry schedule

​Permanent vs. retryable failures

​Auto-disable

​Idempotency

​Ordering

​Testing

​Test delivery button

​Development tools

​Delivery log

​Redelivery

​Integration examples

​PagerDuty

​Slack

​Datadog

​Troubleshooting

​FAQ

​API reference

Quick start

Event catalog

Integrity events (AIP)

Alignment trace events (AAP)

Platform events

Payload envelope

Example payloads

AAP trace event payloads

Security

HMAC-SHA256 signing

Replay protection

Constant-time comparison

Signature verification

Delivery & retries

First delivery

Retry schedule

Permanent vs. retryable failures

Auto-disable

Idempotency

Ordering

Testing

Test delivery button

Development tools

Delivery log

Redelivery

Integration examples

PagerDuty

Slack

Datadog

Troubleshooting

FAQ

API reference