> ## Documentation Index > Fetch the complete documentation index at: https://docs.xtrace.ai/llms.txt > Use this file to discover all available pages before exploring further. # Set webhook config > Create or replace the org's webhook config. Idempotent on `url` / `events` / `enabled`. The full signing `secret` is returned here — on first create, or whenever `rotate_secret=true`. Store it: `GET` only ever returns it masked. ## OpenAPI ````yaml https://api.staging.xtrace.ai/openapi.public.json put /v1/webhooks openapi: 3.1.0 info: title: XTrace Vec DB description: XTrace API version: 1.0.0 servers: - url: https://api.production.xtrace.ai description: Production security: - ApiKeyHeader: [] - BearerToken: [] paths: /v1/webhooks: put: tags: - webhooks summary: Set webhook config description: |- Create or replace the org's webhook config. Idempotent on `url` / `events` / `enabled`. The full signing `secret` is returned here — on first create, or whenever `rotate_secret=true`. Store it: `GET` only ever returns it masked. operationId: put_webhook_v1_webhooks_put parameters: - name: rotate_secret in: query required: false schema: type: boolean description: >- 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. default: false title: Rotate Secret description: >- 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. - name: org_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Org Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookConfigRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/WebhookConfig' '422': description: >- `detail.code = "invalid_webhook_url"` — URL is malformed, not https, or resolves to a non-public address. Or `"invalid_request"` — empty `events`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-codeSamples: - lang: typescript label: TypeScript SDK source: > import { MemoryClient } from '@xtraceai/memory'; const client = new MemoryClient({ apiKey: process.env.XTRACE_API_KEY!, orgId: process.env.XTRACE_ORG_ID!, }); // Create or replace the org's webhook. The full `secret` is returned only // here (first create, or { rotateSecret: true }) — store it to verify // X-Webhook-Signature on incoming deliveries. const wh = await client.webhooks.set({ url: 'https://your-app.com/hooks/xtrace' }); console.log(wh.secret); // whsec_… components: schemas: WebhookConfigRequest: properties: url: type: string title: Url description: >- HTTPS endpoint Xtrace POSTs terminal ingest events to. Must resolve to a public address — private / loopback / link-local hosts are rejected. examples: - https://api.zeabur.example/xtrace/webhooks events: anyOf: - items: type: string enum: - memory.learning.completed - memory.learning.failed type: array - type: 'null' title: Events description: >- Event types to receive. Omit (or null) to subscribe to all events. An empty list is rejected. examples: - - memory.learning.completed - memory.learning.failed enabled: type: boolean title: Enabled description: >- When false, the config is stored but no events are delivered. Lets you pause delivery without losing the URL. default: true type: object required: - url title: WebhookConfigRequest description: '``PUT /v1/webhooks`` — set or replace the org''s webhook config.' WebhookConfig: properties: object: type: string const: webhook title: Object description: Constant discriminator for the resource type. default: webhook url: type: string title: Url description: Configured subscriber URL. events: items: type: string enum: - memory.learning.completed - memory.learning.failed type: array title: Events description: Event types currently subscribed. enabled: type: boolean title: Enabled description: Whether deliveries are active. secret: type: string title: Secret description: >- 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: type: string format: date-time title: Created At description: ISO-8601 timestamp the config was first created. updated_at: anyOf: - type: string - type: 'null' format: date-time title: Updated At description: ISO-8601 timestamp of the most recent edit. type: object required: - url - events - enabled - secret - created_at title: WebhookConfig description: Wire shape of the org's webhook config. ErrorEnvelope: properties: detail: $ref: '#/components/schemas/ErrorDetail' type: object required: - detail title: ErrorEnvelope description: |- Standard error body for non-2xx responses raised by the memory API. Pydantic field-validation failures (422) use the FastAPI- default ``HTTPValidationError`` shape instead, where ``detail`` is an array of per-field error entries — switch on the response status code to pick the right shape. ErrorDetail: properties: code: type: string title: Code description: >- Stable error identifier. Switch on this rather than parsing the message. Common values: `invalid_request`, `invalid_messages`, `memory_not_found`, `job_not_found`, `immutable_field`, `reserved_field`, `empty_text_field`, `missing_user_id`, `missing_conv_id`, `unsupported_include_option`, `cursor_mismatch`, `unauthorized`, `forbidden`, `rate_limited`, `delete_failed`, `search_failed`, `ingest_failed`, `server_error`. examples: - memory_not_found message: type: string title: Message description: Human-readable summary; safe to log but not safe to switch on. examples: - Memory 0fa1c0e6-... not found type: object required: - code - message title: ErrorDetail description: |- Inner ``detail`` block on every non-2xx response raised by a memory-API route handler. ``code`` is the stable identifier clients should switch on; ``message`` is a sanitized human- readable summary. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: 'Long-lived org API key. Alternative: `Authorization: Bearer `.' BearerToken: type: http scheme: bearer bearerFormat: Token description: 'Long-lived API key sent as `Authorization: Bearer `.' ````