Event catalog

Section ID: Guide/e73h61aris#event-catalog

Choose an event by lifecycle, then follow its payload fields and examples. Use the receiver recipe to connect it to your backend or delivery recovery to investigate a missing update. The verification procedure explains the configured webhook signature format. Domain payload examples are not complete HTTP deliveries.

Webhook events

Section ID: Guide/e73h61aris#webhook-events

Manage the receiver through the endpoint and subscription contracts. Use the lifecycle and payload references below to interpret the declared event data.

Delivery envelope

Section ID: Guide/e73h61aris#delivery-envelope

Webhook deliveries use HTTP POST. Preserve the original request body bytes and verify the delivery before parsing or acting on its contents. Event examples on the linked pages describe the event-specific payload; runtime metadata and the HTTP delivery contract are separate.

For a receiver configured for Convoy’s timestamped SHA-256/hex signatures, the signature header is X-Convoy-Signature: t={unix_seconds},v1={hex}. Confirm the endpoint’s configured signature header, algorithm and encoding before enabling the receiver. An unrecognized or missing signature is a rejection, not a reason to bypass verification.

Header	Meaning
X-Convoy-Event-Type	Routing event name. Check it against authenticated event metadata before use.
X-Convoy-Idempotency-Key	{event_id}:{endpoint_id}. Bind it to authenticated event identity and your configured endpoint.
X-Convoy-Signature	Signing timestamp and one or more versioned signatures for the configured verification scheme.

Obtain the endpoint’s secret when creating it, or retrieve the endpoint through List webhook endpoints. Keep the secret on your backend. In the timestamped format above, compute HMAC-SHA256 over the timestamp text, a comma, and the raw request body bytes. Decode the received digest as hex; neither a body-only HMAC nor base64 matches this format.

1. Bound body/header size and the number of signature fields. Reject missing separators, malformed hex, invalid timestamps and repeated timestamp fields without an unhandled error.
2. Require one signing timestamp and at least one supported signature version. Preserve multiple v1 values during a qualified key-overlap period.
3. Enforce a bounded timestamp tolerance with an explicit clock-skew policy. Five minutes is an example receiver setting, not a platform-imposed acceptance window.
4. Compare equal-length decoded digests in constant time against the small configured set of current and overlap secrets. Never log a signing secret or signature. Do not re-serialize parsed JSON: whitespace or key-order changes alter the signed bytes.
5. After signature verification, validate the expected event schema, tenant/project scope and event identity from authenticated delivery metadata. Reject conflicting event-type or idempotency headers; these separate headers are not covered by the body HMAC.
6. Atomically persist the scoped event identity, payload digest and pending work before returning 2xx. Acknowledge an identical duplicate without repeating the work; reject an identity reused with a different payload. If durable acceptance fails, return a non-success response so the configured delivery/reconciliation process can recover it.

Runtime event metadata is supplied in ctx. Use these fields only with a deployment supporting this event contract. The domain payload examples omit runtime metadata and are not complete HTTP deliveries. The Convoy delivery format uses protobuf field names in snake_case, while canonical API model views use their JSON field names.

Delivered metadata field	Meaning
ctx.event_name	Stable event name; compare with the event-type header.
ctx.version	Event schema version.
ctx.event_id	Unique event identity; bind duplicate detection to this value and the endpoint.
ctx.correlation_id	Correlation identifier.
ctx.emitted_at	Event emission time in RFC3339 form; this is separate from the signature timestamp.
ctx.caller_key	Publisher-provided routing key.
ctx.metadata	Application metadata as a string-to-string map.
ctx.tenant_id	Tenant owning the event.
ctx.project_id	Project within that tenant.
ctx.session_id	End-user application session identifier.

After verifying the signature, use signed ctx.event_name for event type and signed ctx.event_id for event identity. Validate ctx.tenant_id and ctx.project_id against the expected scope. Reject conflicting type or idempotency headers. Do not treat a routing header or an invented context field as authenticated metadata.

Timestamp tolerance limits old replays; it does not prevent duplicates inside the window.

Secret rotation: Update webhook endpoint does not accept a secret field, and this public API has no secret-rotation operation. An endpoint metadata update is not evidence that a signing key changed. Qualify any separately supported rotation procedure, receiver overlap and behavior of new/retried deliveries before relying on it.

Event types

Section ID: Guide/e73h61aris#event-types

Choose the lifecycle your application needs, then inspect its selected payload contract:

• Message published — payload fields. An assistant or tool message is produced.
• Generation started — payload fields. A generation run starts.
• Generation completed — payload fields. A generation run reaches a terminal outcome; inspect its status and run identifier.
• Tool call started or awaiting approval — payload fields. A tool call begins execution or waits for human approval; inspect the ToolCall state.
• Tool call completed — payload fields. A tool call reaches a terminal execution result.

Message publication and generation completion can concern the same assistant turn. Keep their lifecycle handlers distinct and correlate their identifiers so they do not trigger the same business action twice.

Payload shapes

Section ID: Guide/e73h61aris#payload-shapes

Follow each selected model to read its field names, types, presence and validation rules. The response view is a canonical domain-data reference; it is not a separate webhook wire contract.

llm.message_published

Section ID: Guide/e73h61aris#llmmessage_published

The message-published Event describes a new assistant or tool message. Read message and the Message model for its content and generation information. Message publication alone is not evidence that a run has reached its terminal outcome.

llm.generation_started

Section ID: Guide/e73h61aris#llmgeneration_started

The generation-started Event marks the start of a run. Inspect runId, startingSequence and the optional config snapshot. The GenerationConfig model describes that configuration. Retain the run identifier with the application work it belongs to.

llm.generation_completed

Section ID: Guide/e73h61aris#llmgeneration_completed

The generation-completed Event marks a terminal run outcome. Inspect runId, status, loopCount, durationMs, usage, error, usageByModel, turnKey. Use Usage, RpcError and UsageByModel for related values. A terminal outcome requires application-specific handling; do not mark every completed run as successful.

Values of status

Section ID: Guide/e73h61aris#llm-generation-completed-values-status

Lifecycle state of a workflow execution, distinct from the reason a terminal execution ended.

Use the selected workflow-status field and its generated enum values for the canonical workflow lifecycle values, numeric values, wire spellings and descriptions. The source distinguishes lifecycle state from the reason a terminal execution ended, and retains the CANCELED wire spelling. The generated contract owns this enum table.

Full payload: LLMGenerationCompletedEvent.

llm.tool_call_started

Section ID: Guide/e73h61aris#llmtool_call_started

The tool-call-started Event describes a call that begins execution or waits for human approval. Read its toolCall and the ToolCall model.

Use isClientTool to distinguish client execution and clientToolDeadlineAt for the result deadline. Match the tool name against the client tools your application declared. For an approval wait, inspect status and requiresApprovalAt. The approval timestamp is a decision deadline, not the time the call began waiting. Reconcile pending work before retrying an action.

llm.tool_call_completed

Section ID: Guide/e73h61aris#llmtool_call_completed

The tool-call-completed Event describes a terminal tool execution result. Read toolCall and executionTimeMs. Inspect the ToolCall state and result before changing application state. A terminal result can require failure handling as well as success handling.

Approval waits

Section ID: Guide/e73h61aris#llmtool_call_approval_required

Human approval is part of the declared tool-call-started lifecycle. Inspect status and requiresApprovalAt on the ToolCall model. The selected catalog does not declare a separate approval-required Event.

Use List pending tool approvals to reconcile calls awaiting a decision and Submit tool approvals to resolve them. Treat a missing deadline as unknown; do not assume the call can wait indefinitely. Check pending state before submitting or repeating a decision.

Conversation updates

Section ID: Guide/e73h61aris#conversation-updates

Conversation updates and scheduled callbacks have their own contracts; do not infer their delivery or recovery rules from a generation Event. Never substitute a conversation activity sequence for a message sequence, or treat an idle conversation as proof that a particular run completed.

Document ID: Guide/e73h61aris