Inbound Webhooks (Developer API)

If a platform isn’t on Comma’s self-serve integrations list, you can still bring it into your archive by pushing messages over HTTPS. Inbound Webhooks give you a per-tenant endpoint that accepts authenticated POSTs and stores the messages alongside everything else.

When to use Inbound Webhooks

• A custom internal app generates messages or events you need archived
• A platform Comma doesn’t natively support has its own outbound webhook feature you can point at us
• A data source (CRM activity log, support tool, audit feed) needs to flow into the same retention system as your communications
• You want a programmatic path to replay historical data after the fact

Endpoint structure

Every endpoint has:

• A public URL in the form https://app.commacompliance.com/webhooks/incoming/in/<token>, where <token> is high-entropy and globally unique to that endpoint
• An auth mode - either Bearer or HMAC
• An optional IP allowlist (CIDR ranges)
• An enabled flag (disable without deleting)
• A name for your dashboard

Authentication

Bearer token

Set Authorization: Bearer <secret> on every request. The secret is generated when you create the endpoint and rotates on demand from the endpoint detail page.

POST /webhooks/incoming/in/abc123tokenxyz HTTP/1.1
Host: app.commacompliance.com
Authorization: Bearer sk_live_REDACTED
Content-Type: application/json

{ "external_id": "msg-42", "from": "alice@example.com", ... }

HMAC

Set X-Comma-Signature: <hex> where <hex> is HMAC-SHA256(secret, request_body). Comma re-computes the signature on receipt and rejects mismatches in constant time.

import hmac, hashlib
sig = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()

Idempotency

Include an external_id field on every message. If the same external_id arrives twice within the dedup window, Comma stores it once and acknowledges both requests with 200. Use this to make your producer safely retryable.

Payload shape

The minimum payload is a JSON object with these fields:

{
  "external_id": "unique-per-message-id",
  "occurred_at": "2026-05-28T14:30:00Z",
  "from": { "identifier": "alice@example.com", "display_name": "Alice" },
  "to": [{ "identifier": "bob@example.com", "display_name": "Bob" }],
  "body": "message text",
  "attachments": []
}

Additional fields are stored as-is on the message record and indexed for search.

Attachments

Attachments can be inline (base64) or referenced by URL. For URL-referenced attachments, Comma fetches them server-side and stores them in WORM storage with the message. Set a content_type and filename so the archive preserves them faithfully.

Rate limits and large payloads

• Soft limit: 100 requests/second per endpoint
• Per-request body cap: 10 MB (for larger attachments, use URL-referenced fetching)
• Burst tolerance: queueing absorbs short bursts; sustained traffic above the limit returns 429

Errors

• 401 Unauthorized - missing or invalid auth header
• 403 Forbidden - source IP not in allowlist
• 422 Unprocessable - payload missing required fields
• 429 Too Many Requests - rate limited; retry with backoff
• 5xx - server error; safe to retry (idempotency protects against duplicates)

Setup steps

1. Sign in to the Comma Compliance dashboard
2. Open Settings > Webhooks > Inbound endpoints
3. Click New endpoint
4. Choose Bearer or HMAC, name the endpoint, optionally set an IP allowlist
5. Copy the URL and the secret (you won’t see the secret again - rotate if lost)
6. Point your producer at the URL and start sending

Rotating secrets

From the endpoint detail page, click Rotate. The old secret is invalidated immediately; the new secret is shown once. Update your producer.

What’s next

• Available on Request integrations - Platforms we capture with concierge setup
• Arc Relay for AI Agent Archiving - For AI provider data feeds