An audit log somebody can actually use

An audit log answers who changed what, when, and what was it before. Most systems record the first three and skip the fourth, which is the one every real investigation needs.

The row

{
  "at": "2026-09-11T14:02:11Z",
  "actor": {"type": "user", "id": "u_18", "email": "jane@example.com"},
  "action": "number.webhook_url.changed",
  "object": {"type": "instance", "id": "in_4f2"},
  "before": {"webhook_url": "https://old.example.com/hook"},
  "after":  {"webhook_url": "https://new.example.com/hook"},
  "ip": "196.201.x.x",
  "request_id": "req_9c1"
}

What each field is for

• actor - and record what they were, not who they are now. A user who has since been deleted still did the thing.
• action - a stable dotted string, never a sentence. Sentences get reworded and then nothing can be filtered.
• before and after - the whole point.
• request_id - so an entry can be joined to the application logs from the same request.

What is worth auditing

Not everything. An audit log of every message is a second copy of the messages table. Audit the things that change what the system does or who can see it:

1. Access changes - members added, roles changed, keys created and revoked.
2. Routing changes - webhook URLs, numbers connected or removed, auto-reply rules.
3. Billing changes - plan, payment method.
4. Bulk actions - an export, an import, a campaign sent.
5. Anything done by an operator on a customer's behalf. This one is not optional; support access without a trail is indistinguishable from a breach.

Append only, and readable

No updates, no deletes, and a screen a customer can read themselves. An audit log only the vendor can see answers the vendor's questions; the question that matters is usually the customer's - "who changed our webhook on Tuesday".