Skip to main content
PUT
/
v1
/
webhooks
Set webhook config
curl --request PUT \
  --url https://api.production.xtrace.ai/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Org-Id: <api-key>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "url": "<string>",
  "events": [
    "memory.learning.completed",
    "memory.learning.failed"
  ],
  "enabled": true
}
'
{
  "url": "<string>",
  "events": [],
  "enabled": true,
  "secret": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "object": "webhook",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
x-api-key
string
header
required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

​
X-Org-Id
string
header
required

Required alongside the API key (no key→org reverse index).

Query Parameters

​
rotate_secret
boolean
default:false

When true, mint a fresh signing secret even if a config already exists. Default false preserves the existing secret so an URL/events edit doesn't break the subscriber.

Body

application/json

PUT /v1/webhooks — set or replace the org's webhook config.

​
url
string
required

HTTPS endpoint Xtrace POSTs terminal ingest events to. Must resolve to a public address — private / loopback / link-local hosts are rejected.

Example:

"https://api.zeabur.example/xtrace/webhooks"

​
events
enum<string>[] | null

Event types to receive. Omit (or null) to subscribe to all events. An empty list is rejected.

Available options:
memory.learning.completed,
memory.learning.failed
Example:
[
  "memory.learning.completed",
  "memory.learning.failed"
]
​
enabled
boolean
default:true

When false, the config is stored but no events are delivered. Lets you pause delivery without losing the URL.

Response

Successful Response

Wire shape of the org's webhook config.

​
url
string
required

Configured subscriber URL.

​
events
enum<string>[]
required

Event types currently subscribed.

Available options:
memory.learning.completed,
memory.learning.failed
​
enabled
boolean
required

Whether deliveries are active.

​
secret
string
required

Signing secret used to verify X-Webhook-Signature. Returned in full only when freshly minted — a first PUT (create) or PUT?rotate_secret=true. Store it then; every other response (a plain edit, or GET) masks it.

​
created_at
string<date-time>
required

ISO-8601 timestamp the config was first created.

​
object
string
default:webhook

Constant discriminator for the resource type.

Allowed value: "webhook"
​
updated_at
string<date-time>

ISO-8601 timestamp of the most recent edit.