Safe Webhook Ingestion Patterns for Rocky

Webhooks let external systems trigger Rocky work. The safe pattern is to authenticate the request, reduce the payload to public-safe context, and make the resulting agent job observable.

Official webhook docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/webhooks

Recommended pattern

• Give each workflow a named route and a specific purpose.
• Require a shared secret, signature, or platform-native verification.
• Normalize incoming payloads before they reach an agent prompt.
• Drop secrets, raw customer records, and unnecessary headers.
• Emit a concise delivery report with job status and next actions.

Payload checklist

• Source system and event type.
• Object ID or public URL when safe.
• Requested action in plain language.
• Deadline or priority if the workflow uses it.
• Explicit exclusions for private data.

Pitfalls

• Accepting unauthenticated POSTs from the public internet.
• Passing entire webhook payloads into a model.
• Letting a webhook trigger deployments without verification gates.
• Failing silently when the downstream agent run errors.
• Mixing test and production endpoints.

Verification steps

• Send a synthetic test payload with no private data.
• Confirm invalid or unsigned requests are rejected.
• Confirm the resulting agent report includes the event ID and action taken.
• Check logs for redaction, replay handling, and useful error messages.