Agent Integration
Your agent backend now receives requests from Convoy instead of directly from your client. You need to do two things:- Verify the request — check Convoy’s HMAC signature
- Report metrics — send latency, outcome, cost, and input/output to Convoy
1. Verify the request
Convoy signs every request it forwards using HMAC-SHA256 with your shared secret. Your agent must verify this signature to confirm the request came from Convoy.Headers Convoy adds
How to verify
- Parse
X-Convoy-Signatureto extractt(timestamp),v1(HMAC), and optionallyv2(HMAC) - Reject if timestamp is older than 5 minutes
- Build the signed payload:
{timestamp}\n{METHOD}\n{path_with_query}\n{body}For example, aPOSTto/api/chat?session=abcwith body{"msg":"hi"}at timestamp1700000000:{path_with_query}is the path of the request as it arrives at your backend, including any query string. Convoy constructs this by concatenating the version’s base path with the client’s request path — for example, a version URL of/api/chatplus a client path of/completionsproduces/api/chat/completions. - Compute HMAC-SHA256 using your secret
- Accept if either
v1orv2matches
During secret rotation, Convoy sends both
v1 (signed with the new secret) and v2 (signed with the old secret) for 24 hours. Your env has one secret — it will match one of them regardless of whether you’ve rotated yet. The code above handles this automatically.2. Report metrics
After your agent processes the request, report metrics to Convoy. This data powers test evaluation — Convoy uses it to decide whether to promote or roll back. Endpoint:POST https://api.convoylabs.com/v1/ingest/sessions
Auth: Authorization: Bearer <CONVOY_SECRET> (same secret)
Payload
Always required:
Required on success, optional on error:
Required on last step (unless
outcome is "error"):
When
outcome is "error", the call may have crashed before producing cost, latency, input, or output. Include these fields if available, but omit them if the data doesn’t exist — don’t fabricate values.
Rules
inputandoutputare required on the last step unlessoutcomeis"error"outputis forbidden whenis_last_stepisfalseinputis allowed on any step — it overwrites the session’s stored input- On success,
outputshould contain everything you want the judge prompt to evaluate — typically the agent’s response, and optionally reasoning or tool calls - For multi-step sessions (e.g. resumed or suspendable workflows), increment
step_indexper step (0,1,2…) and report the final step withis_last_step: true - If your agent retries a step, report each attempt with the same
step_indexbut incrementattempt_number(1,2,3…). All attempts are recorded

