Receive notifications when resources such as Sessions and Agents change. Register a receiver, configure signature verification, and retrieve resource details using the ID in each notification.
First, prepare a receiver URL that is publicly accessible, uses HTTPS on port 443, and accepts POST requests.
Set
Replace
Save the endpoint
After verifying the signature, parse the body and handle the event:
To read Agent output, use
Notifications are sent as HTTPS POST requests with a JSON body. Each delivery attempt times out after 30 seconds.
For further troubleshooting, retain
Choose the events you need and put their complete names from the table in
Some Webhook names differ from those in the Session event stream. For example,
After receiving
After receiving this notification, check the OAuth authorization and refresh configuration, and reauthorize if needed. A
These events describe changes to Agent resources. Read Agent messages and tool calls through the Session event stream.
After receiving
Both scheduled and manual runs send these events.
Scheduled runs send
Deleting a Memory Store also deletes its Memories and versions without individual Memory notifications.
This section covers endpoint management and event record queries.
Create a new Webhook endpoint.
Request Parameters:
Response:
List the Webhook endpoints under the current account.
Request Parameters:
Response:
Response Fields:
Retrieve details of a specific Webhook endpoint.
Path Parameters:
Response:
Update the configuration of a specific Webhook endpoint. Submit only the fields you want to change; omitted fields keep their current values.
Path Parameters:
Request Parameters:
Response:
Example:
Delete the specified Webhook endpoint to stop receiving new event notifications. Notifications already being sent may still arrive.
Path Parameters:
Response:
Enable the specified Webhook endpoint to resume receiving new events. Events produced while the endpoint was disabled are not replayed.
Path Parameters:
Request Parameters: None
Response:
Disable the specified Webhook endpoint to stop receiving new event notifications while keeping its configuration. Notifications already being sent may still arrive.
Path Parameters:
Request Parameters: None
Response:
List the Webhook event records that have been produced, for auditing and troubleshooting.
Returns event records without delivery results. Check your receiver logs to confirm whether a notification was received and processed.
Request Parameters:
Response:
Retrieve detailed information for a single Webhook event record.
Path Parameters:
Response:
API errors such as invalid request parameters use the following format. For example, an event name containing a space returns
Error Fields:
Handle errors by HTTP status and error category; treat
For
Use the official Standard Webhooks library to verify notifications without implementing the signing algorithm yourself. Set
Each delivery includes the following HTTP headers:
Header names are case-insensitive. Pass the received headers directly to the verification library.
Install the dependencies:
Save the following as
Install the dependencies:
Save the following as
These examples demonstrate receipt and verification. Add deduplication and business handling at the comments. For deployment, forward requests from a public HTTPS URL on port 443 to your receiver; the local listening address cannot be registered directly as an endpoint.
Register an Endpoint
First, prepare a receiver URL that is publicly accessible, uses HTTPS on port 443, and accepts POST requests.
Set $QODER_ACCESS_TOKEN to a personal access token (PAT) or service account token (SAT) for management API calls. The signing_secret returned when you create an endpoint is used to verify notifications.
Set QODER_BASE_URL for the region where your resources are located:
| Region | Base URL |
|---|---|
| Global | https://api.qoder.com/api/v1/cloud |
| CN | https://api.qoder.com.cn/api/v1/cloud |
url with your receiver URL. This example subscribes to session.status_idled to receive notifications when the Agent waits for tool actions or new user input.
id and use it as $QODER_WEBHOOK_ENDPOINT_ID in later examples. The signing_secret is returned only at creation, so store it securely.
Before handling notifications, configure signature verification using the raw request body and check the timestamp.
Handle an Event
After verifying the signature, parse the body and handle the event:
- Deduplicate using the top-level
id. Return2xxfor a notification you have already processed. - Handle events according to
data.type. Use the resource lookup table when you need details; apply deletion notifications directly to local records. - Return HTTP
200or another2xxstatus code to acknowledge successful receipt of the notification.
session.status_idled, use data.id as the Session ID. Read Agent output and session.status_idle events with GET /sessions/{id}/events (see List Session events). Use the stream event's stop_reason.type to determine the next action. Common cases include:
requires_action: Confirm a tool call or submit a custom tool result. Follow the examples in Send events to respond to the corresponding tool event. Once all required actions are resolved, the Agent resumes and sendssession.status_run_started.end_turn: The current turn has ended. Read its output to assess the task result.error: The current turn stopped with an error. Read thesession.errorevent from the same turn to investigate.
session.thread_idled, read the corresponding Thread events. Use stop_reason.type from session.thread_status_idle and the output to assess the result. An idle state means the current execution has stopped or is waiting.
GET /sessions/{id} returns the Session's current state. It may still be running while waiting for tool actions, so use the stream events above to determine which actions are required.
Notifications use the following JSON format.
Business Event Example
Field Descriptions
| Field | Type | Description |
|---|---|---|
id | string | Unique notification ID prefixed with whe_; stable across retries and equal to the Webhook-Id header |
created_at | string | Event occurrence time in RFC 3339 UTC format; stable across retries |
type | string | Fixed value "event" |
data | object | Event type and resource identifiers |
data.id | string | ID of the resource associated with the event; see the lookup table below. Thread events use the Session ID and Vault Credential events use the Credential ID |
data.type | string | Event type string, e.g., "session.status_idled", "agent.updated" |
data.session_thread_id | string | (Thread events only) Associated Session Thread ID |
data.vault_id | string | (Vault Credential events only) ID of the Vault it belongs to |
Retrieve the Event's Resource
data contains resource identifiers rather than the full resource content. Replace the path parameters below with fields from the notification, using the same Base URL and access token as the management APIs.
| Event category | GET path | Parameter source |
|---|---|---|
| Session | /sessions/{id} | id = data.id |
| Session Thread | /sessions/{session_id}/threads/{thread_id} | session_id = data.id; thread_id = data.session_thread_id |
| Agent | /agents/{id} | id = data.id |
| Deployment | /deployments/{id} | id = data.id |
| Deployment Run | /deployment_runs/{run_id} | run_id = data.id |
| Environment | /environments/{id} | id = data.id |
| Memory Store | /memory_stores/{id} | id = data.id |
| Vault | /vaults/{id} | id = data.id |
| Vault Credential | /vaults/{vault_id}/credentials/{credential_id} | vault_id = data.vault_id; credential_id = data.id |
GET /sessions/{id}/events; for Thread output, use GET /sessions/{session_id}/threads/{thread_id}/events. Continue through subsequent pages using the response's next_page. See Session events and Thread events for parameters.
A .deleted event means the resource has been deleted, so its GET endpoint may return 404; update your local records from the deletion notification. For other events, GET returns the resource's current state, which may have changed since the notification occurred.
Delivery Behavior
Notifications are sent as HTTPS POST requests with a JSON body. Each delivery attempt times out after 30 seconds.
- Duplicates: The same event can arrive more than once. The top-level
idmatchesWebhook-Idand stays the same across retries. Use it to deduplicate notifications. - Subscription scope: Subscribe before triggering an operation. New subscriptions receive subsequent events; earlier events are not replayed.
- Arrival order: Notifications may arrive out of order. For example, a deletion notification can arrive before an archival notification for the same resource. Retrieve the resource to check its current state; if it has been deleted, handle the deletion notification directly.
- Retries: Each event is attempted at most 3 times per endpoint. After the first failure, the system waits 5–10 seconds to retry. After another failure, it waits 10–20 seconds for the final attempt. Each wait is chosen randomly within its range. Events that still fail are not replayed, and no separate notification reports their loss.
- Responses: Any
2xxacknowledges receipt. A3xxis not retried. Other non-2xxresponses, including4xxand5xx, connection errors, and timeouts follow the retry rules above. - Automatic disabling: The endpoint is disabled immediately if it returns a
3xxresponse or its address resolves to a non-public IP when connecting. Redirects are never followed. The endpoint is also disabled after a sustained period of delivery failures. Any2xxclears the accumulated failure duration.
url. Once the receiver is working again, call POST /webhook_endpoints/{id}/enable. Events produced while the endpoint was disabled are not replayed.
For critical workflows, periodically retrieve resource state and reconcile it with your local records to account for notifications that did not arrive.
Troubleshooting
| Problem | What to do |
|---|---|
Management API returns 400 | Check the URL, event names, nonempty subscription list, and metadata against the response. Event-record queries require an integer record ID, not the whe_ notification ID. |
Management API returns 401 | Check the PAT / SAT. Authentication responses may use code; see Error Response Format. |
Management API returns 404 | Check that the resource ID, access token, and region match, and that the resource has not been deleted. |
Endpoint creation returns 409 | The endpoint count has reached its limit. Remove unused endpoints before retrying. The error type is invalid_request_error. |
| Signature verification fails | Use the signing secret saved when creating the endpoint, preserve the raw body, and check the server clock. |
| No notification arrives | Check that the endpoint is enabled, the subscription existed before the business action, and the URL is publicly reachable, and check receiver logs. |
| Endpoint is automatically disabled | Check disabled_reason, fix the URL or response issue, and call /enable. Events from the disabled period are not replayed. |
| Notifications are duplicated or out of order | Deduplicate by the top-level id and retrieve the resource's current state through GET. |
request_id when available, the notification ID, and receiver logs. A successful business API request does not confirm that the receiver processed the notification.
Supported Event Types
Choose the events you need and put their complete names from the table in events. The following 38 named event types are supported. Wildcard subscriptions are not supported.
Session Events
Some Webhook names differ from those in the Session event stream. For example, session.status_running and session.status_idle in the stream correspond to the session.status_run_started and session.status_idled Webhooks.
When request retries are exhausted, the turn ends and the Session returns to idle; you can send a new message after addressing the error. A child Thread also returns to idle after exhausting its retries and can receive further tasks. A session.status_terminated notification means that the Session has ended. Create a new Session for further work.
| Event Type | Trigger Condition |
|---|---|
session.created | A Session has been created. |
session.updated | Session properties have changed, such as its title, metadata, or configuration. |
session.archived | A Session has been archived. |
session.deleted | A Session has been permanently deleted. |
session.status_run_started | The Session starts or resumes work, including after required tool actions are resolved or a retry resumes execution. |
session.status_idled | The Agent becomes idle, for example when a turn ends, stops with an error, or waits for tool confirmation or custom tool results. |
session.status_rescheduled | A retryable error occurred and the Session is being rescheduled. |
session.status_terminated | The Session has been archived and terminated. |
session.thread_created | A new child Thread has been created in the Session. |
session.thread_idled | A Thread becomes idle, for example when its task ends, stops with an error, or waits for a tool action. This notification can occur for both primary and child Threads. |
session.thread_terminated | A child Thread has been archived and terminated, or an Advisor consultation has completed. |
session.outcome_evaluation_ended | An Outcome evaluation iteration has ended, including a result that requires further revision or an interrupted evaluation. |
session.outcome_evaluation_ended, read outcome_evaluations from GET /sessions/{id} for the latest evaluation state of each Outcome. Interrupting an active Outcome produces result: "interrupted" and sends this notification, even if evaluation has not started yet. For the result of each evaluation iteration, read span.outcome_evaluation_end in the Session event stream. If interrupted before evaluation starts, the record has an empty outcome_evaluation_start_id.
Each resumption produces one session.status_run_started event covering the tool actions completed as part of that resumption. Notifications may be delivered more than once; deduplicate them as described in Handle an Event.
Vault Events
| Event Type | Trigger Condition |
|---|---|
vault.created | A Vault has been created. |
vault.archived | A Vault has been archived. Each credential in it also triggers vault_credential.archived. |
vault.deleted | A Vault has been deleted. Each credential in it also triggers vault_credential.deleted. |
vault_credential.created | A credential has been created. |
vault_credential.archived | A credential has been archived, either individually or along with its Vault. |
vault_credential.deleted | A credential has been deleted, either individually or along with its Vault. |
vault_credential.refresh_failed | An mcp_oauth credential cannot be refreshed, for example because its authorization is invalid, its refresh configuration needs correction, or the OAuth server rejects the refresh request. |
4xx response from the OAuth token endpoint, except 408 and 429, triggers this event even without a standard OAuth error code. Timeouts, rate limits, network errors, and 5xx responses do not trigger it; retry later.
Agent Events
These events describe changes to Agent resources. Read Agent messages and tool calls through the Session event stream.
| Event Type | Trigger Condition |
|---|---|
agent.created | An Agent has been created. |
agent.updated | A new Agent version has been published. |
agent.archived | An Agent has been archived and cannot be used to create new Sessions. |
agent.deleted | An Agent has been permanently deleted. |
Deployment Events
| Event Type | Trigger Condition |
|---|---|
deployment.created | A Deployment has been created. |
deployment.updated | Deployment properties have changed, such as its schedule expression. |
deployment.paused | A Deployment has been paused manually or after its first irrecoverable scheduled-start error, such as an archived Environment or invalid service-account binding. Recoverable errors such as temporary network failures and rate limits do not cause this automatic pause. |
deployment.unpaused | A Deployment has resumed scheduling. |
deployment.archived | A Deployment has been archived. |
deployment.paused, check paused_reason in GET /deployments/{id}. Resolve the issue before resuming the schedule. Archiving the main Agent also archives its associated Deployments and sends deployment.archived. After the main Agent is deleted, a scheduled Deployment is archived on its next trigger without creating that Run. Archive Deployments with no future trigger manually.
Deployment Run Events
Both scheduled and manual runs send these events. data.id identifies the run. Retrieve its session_id with GET /deployment_runs/{run_id}, then use Handle an Event to check the Session state and output.
| Event Type | Trigger Condition |
|---|---|
deployment_run.started | A scheduled run is attempting to create a Session. For compatibility, manual runs send this event after Session creation. |
deployment_run.succeeded | This run has created a Session; this does not mean the task inside the Session has completed or succeeded. |
deployment_run.failed | This run could not create a Session. Retrieve the Deployment Run for error details. |
deployment_run.started before attempting Session creation, followed by deployment_run.succeeded or deployment_run.failed with the same data.id. Manual runs send started and succeeded when a Session is created, or only failed when creation fails. Notifications may arrive out of order or more than once; handle each independently and deduplicate by notification ID.
After the Session is created, track execution timeouts, errors, and completion through Session events and the corresponding status APIs. These outcomes do not change the Run notification reporting whether a Session was created.
Environment Events
| Event Type | Trigger Condition |
|---|---|
environment.created | An Environment has been created. |
environment.updated | Environment fields have changed. An update that changes no fields sends no notification. |
environment.archived | An Environment has been archived. |
environment.deleted | An Environment has been deleted. |
Memory Store Events
| Event Type | Trigger Condition |
|---|---|
memory_store.created | A Memory Store has been created by a user or cloned by the platform. |
memory_store.archived | A Memory Store has been archived. |
memory_store.deleted | A Memory Store has been deleted. |
API Reference
This section covers endpoint management and event record queries. {id} is an endpoint ID except in /webhook_events/{id}, which uses an event record ID.
See Register an Endpoint for the Base URL, access token, and endpoint ID. All endpoints below require Authorization: Bearer $QODER_ACCESS_TOKEN.
POST /webhook_endpoints
Create a new Webhook endpoint.
Request Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | Delivery URL; must be publicly accessible and use HTTPS on port 443 |
description | string | No | Endpoint description for management purposes |
metadata | object | No | Custom string key-value pairs; defaults to {}. At most 16 entries, 64 characters per key, and 512 characters per value |
events | string[] | Yes | Event types to subscribe to, with at least one entry; use complete names from supported event types. Wildcards are not supported |
201 Created
Note: signing_secret is returned only once at creation time; store it securely. See Verify the Signature for how to verify with it.
Status Codes:
| Code | Description |
|---|---|
| 201 | Created successfully |
| 400 | Invalid parameters (for example, a malformed URL, an empty events list, a malformed event name, or invalid metadata) |
| 401 | Unauthorized, invalid or expired token |
| 409 | The per-user endpoint cap has been exceeded; error.type is invalid_request_error |
GET /webhook_endpoints
List the Webhook endpoints under the current account.
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of records to return; default 50, maximum 100 |
200 OK
| Field | Type | Description |
|---|---|---|
id | string | Endpoint unique identifier |
url | string | URL receiving events |
description | string | Endpoint description |
metadata | object | Custom string key-value pairs |
events | string[] | Subscribed event types |
active | boolean | Whether enabled. false when the endpoint has been auto-disabled |
disabled_reason | string | Reason for automatic disabling, when present |
consecutive_fail | integer | Consecutive delivery failure count |
last_success_at | string | Most recent successful delivery time (RFC 3339); omitted if no success is recorded |
last_failure_at | string | Last delivery failure time (RFC 3339); omitted when there are no failures |
created_at | string | Creation time (RFC 3339) |
updated_at | string | Last update time (RFC 3339) |
GET /webhook_endpoints/{id}
Retrieve details of a specific Webhook endpoint.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Webhook endpoint ID |
200 OK
Returns a single endpoint object with the same structure as elements in the list endpoint.
Status Codes:
| Code | Description |
|---|---|
| 200 | Success |
| 404 | Endpoint not found |
PUT /webhook_endpoints/{id}
Update the configuration of a specific Webhook endpoint. Submit only the fields you want to change; omitted fields keep their current values.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Webhook endpoint ID |
| Field | Type | Required | Description |
|---|---|---|---|
url | string | No | Updated delivery URL; must be publicly accessible and use HTTPS on port 443 |
description | string | No | Update endpoint description |
metadata | object | No | Merge by key; null deletes a key and {} leaves existing keys unchanged. The merged object must meet the creation limits |
events | string[] | No | Replace the subscribed event types, with at least one entry |
200 OK
Returns the full updated endpoint object.
Status Codes:
| Code | Description |
|---|---|
| 200 | Updated successfully |
| 400 | Invalid request parameters |
| 404 | Endpoint not found |
DELETE /webhook_endpoints/{id}
Delete the specified Webhook endpoint to stop receiving new event notifications. Notifications already being sent may still arrive.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Webhook endpoint ID |
204 No Content
Status Codes:
| Code | Description |
|---|---|
| 204 | Deleted successfully |
| 404 | Endpoint not found |
POST /webhook_endpoints/{id}/enable
Enable the specified Webhook endpoint to resume receiving new events. Events produced while the endpoint was disabled are not replayed.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Webhook endpoint ID |
200 OK
Returns the endpoint object after enabling (active: true).
Status Codes:
| Code | Description |
|---|---|
| 200 | Enabled successfully |
| 404 | Endpoint not found |
POST /webhook_endpoints/{id}/disable
Disable the specified Webhook endpoint to stop receiving new event notifications while keeping its configuration. Notifications already being sent may still arrive.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | string | Webhook endpoint ID |
200 OK
Returns the endpoint object after disabling (active: false).
Status Codes:
| Code | Description |
|---|---|
| 200 | Disabled successfully |
| 404 | Endpoint not found |
GET /webhook_events
List the Webhook event records that have been produced, for auditing and troubleshooting.
Returns event records without delivery results. Check your receiver logs to confirm whether a notification was received and processed.
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Number of records to return; default 50, maximum 100 |
200 OK
The response's data field contains event records, most recently produced first, or null if there are none. The main fields of each record are:
| Field | Type | Description |
|---|---|---|
id | integer | Event record ID, used to retrieve a single record |
event_type | string | Event type, such as session.status_idled |
payload | object | Notification JSON; payload.id is the notification ID prefixed with whe_ |
created_at | string | Record creation time (RFC 3339) |
GET /webhook_events/{id}
Retrieve detailed information for a single Webhook event record.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
id | integer | Event record ID from the list response; the notification's whe_ ID is not used for this endpoint |
200 OK
Returns a single event record with the same fields as a record in the list response.
Status Codes:
| Code | Description |
|---|---|
| 200 | Success |
| 400 | id is not a valid signed 64-bit integer |
| 404 | Event not found |
Error Response Format
API errors such as invalid request parameters use the following format. For example, an event name containing a space returns 400:
| Field | Type | Description |
|---|---|---|
error.message | string | Human-readable error description |
error.type | string | Error category (e.g., invalid_request_error, not_found_error) |
request_id | string | Request trace ID, returned when available; provide it to support when troubleshooting |
type | string | Fixed value "error" |
message as explanatory text rather than a fixed identifier. See Troubleshooting for next steps.
Authentication failures may use a gateway response instead of the error.type structure above. For example, a missing Authorization header returns HTTP 401:
401, check the access token and read code or error.type according to the returned body.
Verify the Signature
Use the official Standard Webhooks library to verify notifications without implementing the signing algorithm yourself. Set QODER_WEBHOOK_SIGNING_SECRET to the complete signing_secret saved when creating the endpoint, including the whsec_ prefix.
verify() checks the signature and timestamp, then returns the parsed event. It raises an exception if the signature is invalid or the timestamp differs from the current time by more than 5 minutes. Pass the original request body; do not parse and re-serialize JSON before verification.
Request Headers
Each delivery includes the following HTTP headers:
| Header | Value / Description |
|---|---|
Content-Type | application/json; charset=utf-8 |
User-Agent | QoderCloudAgents-Webhook/1.0 |
Webhook-Id | Notification ID, matching the top-level id in the body; stable across retries and used for deduplication |
Webhook-Timestamp | Unix timestamp in seconds for this signature, regenerated on each retry. For business event occurrence time, use the payload's created_at |
Webhook-Signature | Signature value for this delivery |
Webhook-Event-Type | Event type; equals data.type |
Example: Node.js
Install the dependencies:
receiver.cjs and run node receiver.cjs. Register this route before JSON parsing middleware such as express.json().
Example: Python
Install the dependencies:
receiver.py and run flask --app receiver run --port 3000.