Send a Signed Build Notification Through Hermes Webhook Direct Delivery

Use direct delivery for a message whose wording is known before the event arrives. Hermes authenticates and templates the webhook, then hands the result to the configured messaging destination without creating a model turn. It is a useful fit for build status notifications with a narrow, predetermined payload.

  1. Signed test event
  2. Template render
  3. Private destination
Signed test event → Template render → Private destination

Create a private route

Use a development gateway and an isolated messaging destination you control. In the documented webhook route mapping, select a test event such as build_status, pin the signature scheme to generic, store a separate route secret, set deliver_only to true, and select a real delivery target supported by your messaging adapter. The docs require an actual destination for direct delivery. A log-only destination cannot exercise this mode.

Use a minimal template such as “Fixture build {build} returned {result}.” Validate and allowlist both values before sending, or use a constant template for the initial smoke test. Avoid interpolating commit messages or arbitrary markdown until the destination's escaping and mention behavior have been verified.

Sign exactly the bytes sent

The current generic V2 scheme signs the decimal Unix timestamp, a dot, and the raw body using HMAC-SHA256. Supply the documented X-Webhook-Timestamp and X-Webhook-Signature-V2 headers. Use the route's current required event and delivery headers. The documented webhook test command provides a way to create a compatible test event for a configured route. Consult its help and confirm which route options it reads before using it against a real destination.

Test a valid request, a signature calculated for different bytes, and a stale timestamp. Only the authorized case should produce a notice. For a test with repeats, reuse the documented delivery identifier and measure the observed suppression behavior. A success HTTP status can also represent a filtered or otherwise ignored event, so inspect the result and the private destination.

Operate it safely

Keep the receiver private where practical and use TLS across network boundaries. Store the route key in approved secret configuration and use synchronized clocks. Rotate the credential if it was exposed. Authentication identifies an authorized sender. It gives no assurance that fields are safe to interpolate into a message.

Does direct delivery use model tokens? The documented path skips starting the agent. Messaging-provider limits and its own retry rules still apply.

When should I use an agent route? Use it when the output needs a reasoned summary or a tool-backed investigation with an appropriate trust boundary.

References

Official Hermes Agent documentation · ASP.NET PB on duplicate requests

Comments