Verify Webhook requests and reliably process events that may be delivered more than once.
Webhook is currently in Beta. APIs, fields, and behavior may change in future versions.
HTTP request
When an event occurs, Qoder Cloud Agents sends an HTTP POST request to the Endpoint URL:
| Header | Description |
|---|---|
Webhook-ID | Event ID. It remains the same across retries and can be used as the consumer idempotency key. |
Webhook-Event-Type | Event type. |
Webhook-Timestamp | Unix timestamp in seconds used to generate the signature. |
Webhook-Signature | Request signature, currently formatted as v1,<base64>. |
2xx response indicates successful processing. Verify the signature, write the event to your reliable queue, and return the response promptly.
Event structure
Forward business events use a common envelope:
| Field | Type | Description |
|---|---|---|
type | string | Always event. |
id | string | Webhook event ID. Matches Webhook-ID. |
created_at | string | Event time, in RFC 3339 format. |
data.type | string | Event type. Matches Webhook-Event-Type. |
data.id | string | ID of the affected resource; for management tool query or failure events, the stcall_* call-record ID. |
data.schema_version | integer | Event data version. Currently 1. |
Schedule events
The data of all five Schedule events below includes source and source_session_id. See Schedule creation source for their meaning. Run events inherit the parent Schedule's creation source.
Events newly enqueued after service deployment always include both fields. Historical events and their retries may omit them, so clients must tolerate missing fields. If needed, query the source through Get a schedule or Get a schedule run.
forward.schedule.created
Sent when a Schedule is created successfully:
trigger_policy_type and next_trigger_at are returned only when values are available.
forward.schedule.updated
Sent when update_forward_schedule actually modifies a Schedule and the tool result is updated. This covers both Forward’s built-in MCP and legacy Custom Tool invocation paths. Calling the HTTP Update Schedule API directly does not produce this event.
| Field | Description |
|---|---|
schedule_id | ID of the modified Schedule, the same as data.id. |
identity_id, template_id | Identity and Template that the Schedule belongs to. |
status | Resource status of the Schedule after the update, such as active or paused; not the tool result updated. |
updated_at | The update time actually saved for this change, in UTC RFC 3339 format with microsecond precision. The outer created_at corresponds to this time. |
schedule_version | Integer configuration version of the Schedule after this update. Independent of the event structure version schema_version and execution input version initial_events_version. |
source, source_session_id | The Schedule’s creation source, not the source or Session of this update. For API creation, these are api and null; for tool creation, they are tool and the ID of the Session that created it. |
trigger_policy_type, next_trigger_at | Trigger policy type and next trigger time after the update. Returned when corresponding values are available. |
tool_call to describe this update invocation; successful events from the MCP path do not include this correlation object.
The Schedule change and notification event are saved in the same transaction. When the updated configuration matches the current configuration, the tool returns unchanged without writing to the Schedule or sending success or failure notifications. The caller can still view the tool result in the current Session. Historical updates do not receive backfilled notifications.
Delivery retries for the same change reuse Webhook-ID; a subsequent actual change produces a new event ID. Receivers should deduplicate by Webhook-ID, not just by Schedule ID. Events are not guaranteed to arrive in update order. When synchronizing a Schedule’s configuration, use schedule_version or query its current details to avoid overwriting a newer version with an older one.
Existing Endpoints must add forward.schedule.updated to events; Endpoints subscribed to * receive it automatically. Deterministic update failures use forward.schedule.update_failed; see Management tool results. This event is independent of Schedule Run execution results.
forward.schedule.archived
Sent when a Schedule first changes from unarchived to archived. data.status is always archived.
This covers the following archive paths:
- Calling the archive API or the
delete_forward_scheduletool in a Session. - Batch archiving, with one event for each Schedule actually archived by that operation.
- Automatic archiving after a one-time task finishes, or when a trigger plan has no next run because of
stop_at. - Cascaded archiving when clearing an Identity, and archiving triggered by unavailable dependencies. Pausing a Schedule alone does not send this event.
| Field | Description |
|---|---|
schedule_id | ID of the archived Schedule, the same as data.id. |
identity_id, template_id | Identity and Template that the Schedule belongs to. |
source, source_session_id | The Schedule's creation source, not the source of this archive operation. For API creation, these are api and null; for tool creation, they are tool and the ID of the Session that created it. |
status | Always archived. When querying a Schedule object, continue to determine its archive state from a non-null archived_at. |
archived_at | Actual archive time in RFC 3339 format. The outer created_at corresponds to this time. |
Webhook-ID. Previously archived historical data does not receive backfilled notifications.
This event means the Schedule is archived. It does not mean existing Runs have finished or that all other cleanup steps for clearing an Identity are complete. Delivery order is not guaranteed between archive, creation, and Run result notifications. When synchronizing local state, do not let a late creation notification reactivate an archived task.
This is a separate Webhook notification and does not add an archive event to the Session. Existing Endpoints must add forward.schedule.archived to events; Endpoints subscribed to * receive it automatically.
forward.schedule_run.succeeded
Sent when a Schedule Run completes successfully. data.status is completed.
forward.schedule_run.failed
Sent when a Schedule Run fails. The structure is the same as the success event, data.status is failed, and error_type may be included:
Schedule Run input version
forward.schedule_run.succeeded and forward.schedule_run.failed include the following field when the execution input version is known:
| Field | Type | Description |
|---|---|---|
data.initial_events_version | integer (optional) | Input version selected for the current execution attempt of this Run, matching the Run query response; omitted when unknown. |
data.schema_version, which describes the event structure. Callback redelivery preserves the original event's input version. Later Schedule updates do not change queued callbacks, and callbacks do not additionally include the complete initial_events. Historical events or callbacks for Runs whose input version cannot be confirmed may omit this field. Receivers must treat it as unknown, without substituting the current Schedule version or interpreting absence as 0. See Schedule input version for the complete version and attempt semantics.
Use the corresponding Schedule Run query API as the source of truth for business results. Webhooks notify you of status changes.
To retrieve the full input, use data.run_id from the callback to get the Schedule Run with include_initial_events=true. The response includes initial_events only when the input for that attempt is bound and can be confirmed. Do not substitute the current Schedule configuration for that input.
Schedule management tool results
These notifications cover the create, query, update, and archive Schedule tools in Forward's built-in MCP and legacy Custom Tool paths. They represent the result of a management operation, independently of Schedule Run execution success or failure.
| Tool | Success event | Failure or input-required event |
|---|---|---|
create_forward_schedule | forward.schedule.created | forward.schedule.create_failed |
list_forward_schedules | forward.schedule.queried | forward.schedule.query_failed |
update_forward_schedule | forward.schedule.updated, only when an actual change occurs | forward.schedule.update_failed |
delete_forward_schedule | forward.schedule.archived | forward.schedule.archive_failed |
schedule_match_ambiguous and require a specific Schedule ID. No candidate is archived.
For complete creation failure scenarios, error codes, and entry-point differences, see natural-language creation failures and error codes. Read Webhook error codes from data.error.code; synchronous tool results may use a different location.
The update tool sends forward.schedule.updated when its result is updated, and sends no notification for unchanged. Deterministic business failures, no query matches, or multiple query matches produce forward.schedule.update_failed; multiple matches require the user to select a specific ID. This failure event does not indicate a Schedule Run execution failure.
Successful query example
Archive selection required example
Result fields and correlation
The following table applies to successful queries and management tool failure events. For successful creation, updates, and archiving, see the resource event descriptions above.
| Field | Description |
|---|---|
data.id | The stcall_* call-record ID, equal to data.tool_call.id. |
data.source | Always tool. tool_call.session_id identifies the Session of the current call. |
data.tool_call | Call correlation information: id, name, and session_id. The MCP path also includes invocation_path=mcp and optional turn_id. The legacy Custom Tool path includes source_event_id, tool_use_id or custom_tool_use_id, and optional session_thread_id. Only correlation fields actually supplied by the source are returned. |
data.result | Returned only for successful queries. Contains schedules, count, has_more, and limit. Schedule summaries contain only ID, name, status, and trigger-policy summaries; next_trigger_at is returned when available. Task instructions, full execution configuration, and credentials are excluded. With no matches, schedules=[] and count=0. |
data.error | Returned for failures or required user input. Contains code, category, message, and requires_input. Categories include invalid_request, forbidden, not_found, and requires_input. |
tool_call. Create and archive events may also include schedule_version; update events always include this version. Success notifications from the MCP path use the resource event structure without tool_call. In resource events, source and source_session_id still describe how the Schedule was created; tool_call describes the current management call.
These result notifications are enabled by default, but Endpoints must subscribe to the corresponding full event names. A * subscription receives the new events; prefix wildcards such as forward.schedule.* are unsupported. Business-failure notifications are not guaranteed when the trusted call source cannot be confirmed, infrastructure fails, or the commit outcome is uncertain.
Delivery retries for the same persisted event reuse Webhook-ID; use it for deduplication. Replaying a recorded legacy Custom Tool call does not modify the Schedule again or generate a new success event. stcall_* correlates notifications and is not an idempotency key for the upstream tool call. Separate MCP requests execute independently: do not automatically retry create, update, or archive operations because an outcome is uncertain. Do not rely on the arrival order of management and Run notifications.
Managed Agents resource events
Forward also supports subscribing to Session, Session Thread, Agent, Environment, Memory Store, Vault, and Vault Credential events. See Supported public events for full event names and triggers.
These events use the same outer envelope, but data carries only a resource reference. It does not include the schema_version, business status, or result body of Schedule events. For example, when a Session becomes idle:
| Event family | data.id | Additional fields |
|---|---|---|
session.status_*, session.updated, session.deleted | Session ID | None. |
session.thread_* | ID of the parent Session | session_thread_id: the specific thread ID. |
agent.* | Managed Agent ID | None. |
environment.* | Environment ID | None. |
memory_store.* | Memory Store ID | None. |
vault.* | Vault ID | None. |
vault_credential.* | Vault Credential ID | vault_id: ID of the parent Vault. |
* in this table only groups event families. It is not a prefix wildcard you can put in events. After a notification arrives, query the current details by resource ID. Resources referenced by deletion events may no longer be queryable. session.status_idled does not mean the business run succeeded; judge the outcome from the Session output and status.
webhook.test does not use the resource event structure above. See Send a test event for its payload.
Verify signatures
The signing_secret returned when an Endpoint is created verifies request signatures. The signed content combines three parts:
Webhook-Timestampdiffers from the current time by no more than five minutes.Webhook-Signaturecontains at least one validv1signature.- A previously processed
Webhook-IDdoes not repeat side-effecting business operations.
Retries and idempotency
Webhook delivery is at least once. The system may retry the same event after a network failure, timeout, or non-2xx response.
- Deduplicate using
Webhook-ID. Do not generate an idempotency key from the arrival time. - Return success for duplicate requests with the same
Webhook-ID, and do not repeat side effects. - Return non-
2xxon processing failure. Return2xxafter successful processing or when the event was already processed.