Skip to main content

Webhook

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.

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:
RegionBase URL
Globalhttps://api.qoder.com/api/v1/cloud
CNhttps://api.qoder.com.cn/api/v1/cloud
Replace 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.
curl -X POST "$QODER_BASE_URL/webhook_endpoints" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/qoder",
    "description": "Session notifications",
    "events": ["session.status_idled"]
  }'
Save the endpoint 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:
  1. Deduplicate using the top-level id. Return 2xx for a notification you have already processed.
  2. Handle events according to data.type. Use the resource lookup table when you need details; apply deletion notifications directly to local records.
  3. Return HTTP 200 or another 2xx status code to acknowledge successful receipt of the notification.
When you receive 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 sends session.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 the session.error event from the same turn to investigate.
For 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

{
  "id": "whe_a1b2c3d4e5f67890",
  "created_at": "2026-07-02T10:02:16Z",
  "type": "event",
  "data": {
    "id": "sess_019f224773fe71d79c5869bd089d159c",
    "type": "session.status_idled"
  }
}

Field Descriptions

FieldTypeDescription
idstringUnique notification ID prefixed with whe_; stable across retries and equal to the Webhook-Id header
created_atstringEvent occurrence time in RFC 3339 UTC format; stable across retries
typestringFixed value "event"
dataobjectEvent type and resource identifiers
data.idstringID 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.typestringEvent type string, e.g., "session.status_idled", "agent.updated"
data.session_thread_idstring(Thread events only) Associated Session Thread ID
data.vault_idstring(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 categoryGET pathParameter 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
To read Agent output, use 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 id matches Webhook-Id and 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 2xx acknowledges receipt. A 3xx is not retried. Other non-2xx responses, including 4xx and 5xx, connection errors, and timeouts follow the retry rules above.
  • Automatic disabling: The endpoint is disabled immediately if it returns a 3xx response 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. Any 2xx clears the accumulated failure duration.
If the receiver address changes, update the endpoint's 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

ProblemWhat to do
Management API returns 400Check 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 401Check the PAT / SAT. Authentication responses may use code; see Error Response Format.
Management API returns 404Check that the resource ID, access token, and region match, and that the resource has not been deleted.
Endpoint creation returns 409The endpoint count has reached its limit. Remove unused endpoints before retrying. The error type is invalid_request_error.
Signature verification failsUse the signing secret saved when creating the endpoint, preserve the raw body, and check the server clock.
No notification arrivesCheck 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 disabledCheck 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 orderDeduplicate by the top-level id and retrieve the resource's current state through GET.
For further troubleshooting, retain 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 TypeTrigger Condition
session.createdA Session has been created.
session.updatedSession properties have changed, such as its title, metadata, or configuration.
session.archivedA Session has been archived.
session.deletedA Session has been permanently deleted.
session.status_run_startedThe Session starts or resumes work, including after required tool actions are resolved or a retry resumes execution.
session.status_idledThe Agent becomes idle, for example when a turn ends, stops with an error, or waits for tool confirmation or custom tool results.
session.status_rescheduledA retryable error occurred and the Session is being rescheduled.
session.status_terminatedThe Session has been archived and terminated.
session.thread_createdA new child Thread has been created in the Session.
session.thread_idledA 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_terminatedA child Thread has been archived and terminated, or an Advisor consultation has completed.
session.outcome_evaluation_endedAn Outcome evaluation iteration has ended, including a result that requires further revision or an interrupted evaluation.
After receiving 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 TypeTrigger Condition
vault.createdA Vault has been created.
vault.archivedA Vault has been archived. Each credential in it also triggers vault_credential.archived.
vault.deletedA Vault has been deleted. Each credential in it also triggers vault_credential.deleted.
vault_credential.createdA credential has been created.
vault_credential.archivedA credential has been archived, either individually or along with its Vault.
vault_credential.deletedA credential has been deleted, either individually or along with its Vault.
vault_credential.refresh_failedAn 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.
After receiving this notification, check the OAuth authorization and refresh configuration, and reauthorize if needed. A 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 TypeTrigger Condition
agent.createdAn Agent has been created.
agent.updatedA new Agent version has been published.
agent.archivedAn Agent has been archived and cannot be used to create new Sessions.
agent.deletedAn Agent has been permanently deleted.

Deployment Events

Event TypeTrigger Condition
deployment.createdA Deployment has been created.
deployment.updatedDeployment properties have changed, such as its schedule expression.
deployment.pausedA 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.unpausedA Deployment has resumed scheduling.
deployment.archivedA Deployment has been archived.
After receiving 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 TypeTrigger Condition
deployment_run.startedA scheduled run is attempting to create a Session. For compatibility, manual runs send this event after Session creation.
deployment_run.succeededThis run has created a Session; this does not mean the task inside the Session has completed or succeeded.
deployment_run.failedThis run could not create a Session. Retrieve the Deployment Run for error details.
Scheduled runs send 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 TypeTrigger Condition
environment.createdAn Environment has been created.
environment.updatedEnvironment fields have changed. An update that changes no fields sends no notification.
environment.archivedAn Environment has been archived.
environment.deletedAn Environment has been deleted.

Memory Store Events

Event TypeTrigger Condition
memory_store.createdA Memory Store has been created by a user or cloned by the platform.
memory_store.archivedA Memory Store has been archived.
memory_store.deletedA Memory Store has been deleted.
Deleting a Memory Store also deletes its Memories and versions without individual Memory notifications.

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:
FieldTypeRequiredDescription
urlstringYesDelivery URL; must be publicly accessible and use HTTPS on port 443
descriptionstringNoEndpoint description for management purposes
metadataobjectNoCustom string key-value pairs; defaults to {}. At most 16 entries, 64 characters per key, and 512 characters per value
eventsstring[]YesEvent types to subscribe to, with at least one entry; use complete names from supported event types. Wildcards are not supported
Response: 201 Created
{
  "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
  "url": "https://your-app.example.com/webhooks/qoder",
  "description": "quickstart demo",
  "events": ["session.status_idled", "session.thread_idled"],
  "metadata": {},
  "active": true,
  "signing_secret": "whsec_O30snlHwqEFj1b4Hwq+RONpG4LV8HzmC6l0MRrmPc1E=",
  "created_at": "2026-07-02T18:17:30.069191+08:00"
}
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:
CodeDescription
201Created successfully
400Invalid parameters (for example, a malformed URL, an empty events list, a malformed event name, or invalid metadata)
401Unauthorized, invalid or expired token
409The 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:
ParameterTypeRequiredDescription
limitintegerNoNumber of records to return; default 50, maximum 100
Response: 200 OK
{
  "data": [
    {
      "id": "700e7789-edab-41cb-b60a-210d0df38ab6",
      "url": "https://your-app.example.com/webhooks/qoder",
      "description": "prod app hook",
      "events": ["session.status_idled", "session.thread_idled"],
      "metadata": {},
      "active": true,
      "consecutive_fail": 0,
      "last_success_at": "2026-07-02T18:08:12.666783+08:00",
      "created_at": "2026-07-02T17:47:16.073822+08:00",
      "updated_at": "2026-07-02T17:47:16.073822+08:00"
    }
  ]
}
Response Fields:
FieldTypeDescription
idstringEndpoint unique identifier
urlstringURL receiving events
descriptionstringEndpoint description
metadataobjectCustom string key-value pairs
eventsstring[]Subscribed event types
activebooleanWhether enabled. false when the endpoint has been auto-disabled
disabled_reasonstringReason for automatic disabling, when present
consecutive_failintegerConsecutive delivery failure count
last_success_atstringMost recent successful delivery time (RFC 3339); omitted if no success is recorded
last_failure_atstringLast delivery failure time (RFC 3339); omitted when there are no failures
created_atstringCreation time (RFC 3339)
updated_atstringLast update time (RFC 3339)

GET /webhook_endpoints/{id}

Retrieve details of a specific Webhook endpoint. Path Parameters:
ParameterTypeDescription
idstringWebhook endpoint ID
Response: 200 OK Returns a single endpoint object with the same structure as elements in the list endpoint. Status Codes:
CodeDescription
200Success
404Endpoint 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:
ParameterTypeDescription
idstringWebhook endpoint ID
Request Parameters:
FieldTypeRequiredDescription
urlstringNoUpdated delivery URL; must be publicly accessible and use HTTPS on port 443
descriptionstringNoUpdate endpoint description
metadataobjectNoMerge by key; null deletes a key and {} leaves existing keys unchanged. The merged object must meet the creation limits
eventsstring[]NoReplace the subscribed event types, with at least one entry
Response: 200 OK Returns the full updated endpoint object. Status Codes:
CodeDescription
200Updated successfully
400Invalid request parameters
404Endpoint not found
Example:
curl -X PUT "$QODER_BASE_URL/webhook_endpoints/$QODER_WEBHOOK_ENDPOINT_ID" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["session.status_idled", "session.thread_idled", "agent.updated"],
    "description": "updated prod hook"
  }'

DELETE /webhook_endpoints/{id}

Delete the specified Webhook endpoint to stop receiving new event notifications. Notifications already being sent may still arrive. Path Parameters:
ParameterTypeDescription
idstringWebhook endpoint ID
Response: 204 No Content Status Codes:
CodeDescription
204Deleted successfully
404Endpoint 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:
ParameterTypeDescription
idstringWebhook endpoint ID
Request Parameters: None Response: 200 OK Returns the endpoint object after enabling (active: true). Status Codes:
CodeDescription
200Enabled successfully
404Endpoint 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:
ParameterTypeDescription
idstringWebhook endpoint ID
Request Parameters: None Response: 200 OK Returns the endpoint object after disabling (active: false). Status Codes:
CodeDescription
200Disabled successfully
404Endpoint 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:
ParameterTypeRequiredDescription
limitintegerNoNumber of records to return; default 50, maximum 100
Response: 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:
FieldTypeDescription
idintegerEvent record ID, used to retrieve a single record
event_typestringEvent type, such as session.status_idled
payloadobjectNotification JSON; payload.id is the notification ID prefixed with whe_
created_atstringRecord creation time (RFC 3339)

GET /webhook_events/{id}

Retrieve detailed information for a single Webhook event record. Path Parameters:
ParameterTypeDescription
idintegerEvent record ID from the list response; the notification's whe_ ID is not used for this endpoint
Response: 200 OK Returns a single event record with the same fields as a record in the list response. Status Codes:
CodeDescription
200Success
400id is not a valid signed 64-bit integer
404Event 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:
{
  "error": {
    "message": "Invalid event type: session idled",
    "type": "invalid_request_error"
  },
  "request_id": "cc865161-b25d-4d68-bad5-bf0363f6e0f9",
  "type": "error"
}
Error Fields:
FieldTypeDescription
error.messagestringHuman-readable error description
error.typestringError category (e.g., invalid_request_error, not_found_error)
request_idstringRequest trace ID, returned when available; provide it to support when troubleshooting
typestringFixed value "error"
Handle errors by HTTP status and error category; treat 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:
{
  "code": "TOKEN_INVALID",
  "message": "missing authorization token",
  "timestamp": "1792982170292"
}
For 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:
HeaderValue / Description
Content-Typeapplication/json; charset=utf-8
User-AgentQoderCloudAgents-Webhook/1.0
Webhook-IdNotification ID, matching the top-level id in the body; stable across retries and used for deduplication
Webhook-TimestampUnix timestamp in seconds for this signature, regenerated on each retry. For business event occurrence time, use the payload's created_at
Webhook-SignatureSignature value for this delivery
Webhook-Event-TypeEvent type; equals data.type
Header names are case-insensitive. Pass the received headers directly to the verification library.

Example: Node.js

Install the dependencies:
npm install express standardwebhooks
Save the following as receiver.cjs and run node receiver.cjs. Register this route before JSON parsing middleware such as express.json().
const express = require('express');
const { Webhook } = require('standardwebhooks');

const app = express();
const webhook = new Webhook(process.env.QODER_WEBHOOK_SIGNING_SECRET);

app.post('/webhooks/qoder', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers);
  } catch {
    return res.status(400).send('Invalid webhook');
  }

  try {
    // Deduplicate by event.id and handle the event here; return 5xx on processing failure.
    if (event.data.type === 'session.status_idled') {
      // Use event.data.id to fetch the Session and its events, then run your business logic.
    }
    return res.sendStatus(200);
  } catch {
    return res.sendStatus(500);
  }
});

app.listen(3000);

Example: Python

Install the dependencies:
pip install flask standardwebhooks
Save the following as receiver.py and run flask --app receiver run --port 3000.
import os

from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
webhook = Webhook(os.environ["QODER_WEBHOOK_SIGNING_SECRET"])


@app.post("/webhooks/qoder")
def receive_webhook():
    try:
        event = webhook.verify(request.get_data(), dict(request.headers))
    except (WebhookVerificationError, ValueError):
        return "Invalid webhook", 400

    # Deduplicate by event["id"] and handle the event here; Flask returns 500 on an unhandled error.
    if event["data"]["type"] == "session.status_idled":
        # Use event["data"]["id"] to fetch the Session and its events, then run your business logic.
        pass
    return "", 200
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.