Webhook Design for LLMs
Designing webhooks that ship structured signals to an LLM router is a different problem than designing webhooks for humans. The payload must be small, schema-stable, and self-describing so the model can route, classify, and respond without a second round-trip. This recipe covers the three rules we follow on Meridian.
1.Keep the envelope flat and typed
LLMs route faster on flat JSON. Nested objects waste tokens and slow down classification. Promote the signal fields to the top level and reserve a single data field for the raw provider payload. Type every key so the router never guesses.
{
"event": "invoice.payment_failed",
"tenant": "acct_19fA",
"severity": "high",
"summary": "Card declined for $129.00",
"ts": 1735329600,
"data": { /* raw provider body */ }
}2.Pre-compute a one-line summary
The summary field is the single most useful key in an LLM-bound webhook. It gives the model a deterministic anchor sentence to quote back to the user, even if the model never reads data. Generate it server-side from the same source of truth you use for your dashboard so the human and the model see the same story.
3.Sign and version every payload
Add a v field and an HMAC signature header. When a model retries, you want to know which schema it saw. Bump the version when you change field semantics, never when you only add optional keys. The router can then degrade gracefully on older payloads instead of refusing to act.