> ## Documentation Index > Fetch the complete documentation index at: https://docs.centaur.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook endpoint > Registers an HTTPS endpoint for the event types you choose. The response carries the signing secret once: store it to verify the `Centaur-Signature` header of each delivery. An account can have at most five endpoints. ## OpenAPI ````yaml /openapi-v2.json post /webhooks openapi: 3.1.0 info: title: Centaur API version: 2.0.0 description: >- Public API for reading Centaur's data over REST, with a companion MCP surface, and for partners to manage the webhook endpoints that receive Centaur events. servers: - url: https://api.centaur.io/v2 description: Centaur API v2 security: [] tags: - name: System description: Health and service metadata endpoints. - name: Discovery description: Read-only trader and asset directory discovery endpoints. - name: Events description: >- Historical trade-event reads with source, trader, asset, and position context. - name: Messages description: >- Read-only access to source messages by message timestamp or Source Message ID. - name: Channel Summaries description: Generated channel narrative summaries selected by Source Window overlap. - name: Aggregate Summaries description: >- Generated aggregate narrative summaries selected by Aggregate Window overlap. - name: Positions description: Read-only position history and open-position live state reads. - name: Stats description: Read-only aggregate trader and asset stats. - name: Webhooks description: >- Register HTTPS endpoints that receive signed event deliveries, manage their state and secrets, replay past deliveries and inspect delivery history. Requires the `webhooks.manage` permission on a partner account. - name: Widgets description: >- Hosted widget reads restricted to enabled registrations and approved origins. externalDocs: description: Canonical Centaur API documentation url: https://docs.centaur.io paths: /webhooks: post: tags: - Webhooks summary: Create a webhook endpoint description: >- Registers an HTTPS endpoint for the event types you choose. The response carries the signing secret once: store it to verify the `Centaur-Signature` header of each delivery. An account can have at most five endpoints. operationId: createWebhookEndpoint requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreate' responses: '201': description: The created endpoint with its signing secret content: application/json: example: success: true data: id: 3f0c8a52-6a7e-4d0b-9b5e-2f1c7d9e4a10 url: https://hooks.example.com/centaur description: Production trade alerts eventTypes: - trade_event.created - feed_item.created - feed_item.updated filters: traderIds: - 7 assetClasses: - crypto status: ACTIVE statusChangedAt: '2026-10-05T10:00:00.000Z' disabledReason: null maxInFlight: 5 consecutiveFailures: 0 lastSuccessAt: null lastFailureAt: null lastSequence: 0 secretRotatedAt: null previousSecretExpiresAt: null createdAt: '2026-10-05T10:00:00.000Z' updatedAt: '2026-10-05T10:00:00.000Z' secret: whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8 requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: type: object properties: success: type: boolean enum: - true data: $ref: '#/components/schemas/WebhookEndpointWithSecret' requestId: type: string example: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 required: - success - data - requestId '401': description: Missing or invalid API key content: application/json: example: success: false error: code: UNAUTHORIZED message: Unauthorized requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: >- The API key lacks the `webhooks.manage` permission, or the account is not an active partner account (`PARTNER_REQUIRED`, `PARTNER_SUSPENDED`) content: application/json: example: success: false error: code: FORBIDDEN message: API key lacks webhooks.manage permission requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: The account already has the maximum number of endpoints content: application/json: example: success: false error: code: ENDPOINT_LIMIT_REACHED message: >- A partner can have at most 5 webhook endpoints. Delete one first. requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: >- Request validation failed, or the URL is not allowed (`UNSAFE_URL`) or does not resolve (`URL_NOT_RESOLVABLE`) content: application/json: example: success: false error: code: UNSAFE_URL message: >- The URL host resolves to a private, loopback, link-local or metadata address. requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Authentication service temporarily unavailable headers: Retry-After: description: Seconds to wait before retrying authentication schema: type: integer minimum: 1 content: application/json: example: success: false error: code: AUTHENTICATION_UNAVAILABLE message: Authentication is temporarily unavailable requestId: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 schema: $ref: '#/components/schemas/ErrorEnvelope' security: - ApiKeyAuth: [] components: schemas: WebhookEndpointCreate: type: object properties: url: type: string maxLength: 2048 format: uri description: >- HTTPS URL that receives deliveries as signed POST requests. Its host must be public: a host that is or resolves to a private, loopback, link-local or cloud metadata address is rejected, and URLs with a username or password are rejected. description: type: string maxLength: 256 description: Your label for the endpoint. Display only. eventTypes: type: array items: $ref: '#/components/schemas/WebhookEventType' minItems: 1 description: Event types the endpoint subscribes to. At least one, no duplicates. filters: type: object properties: traderIds: type: array items: type: integer exclusiveMinimum: 0 minItems: 1 maxItems: 100 description: >- Deliver only events of these trader IDs. Omit for no trader filtering. sourceIdentityIds: type: array items: type: string minLength: 1 description: >- Opaque platform-scoped source identity ID for the source account or channel. minItems: 1 maxItems: 100 description: >- Deliver only events from these opaque source identity IDs (the `source.identity.sourceIdentityId` values). Omit for no source filtering. assetIds: type: array items: type: integer exclusiveMinimum: 0 minItems: 1 maxItems: 100 description: >- Deliver only events on these asset IDs. Omit for no asset filtering. assetClasses: type: array items: type: string enum: - crypto - stocks - indices - commodities - fx minItems: 1 maxItems: 100 description: >- Deliver only events on assets of these classes: crypto, stocks, indices, commodities, or fx. Omit for no asset-class filtering. additionalProperties: false description: >- Subscription filters. Omit for no filtering. Applies to `trade_event.*` and `feed_item.*` deliveries only. maxInFlight: type: integer minimum: 1 maximum: 50 description: >- Maximum deliveries sent to this endpoint at the same time, 1 to 50. Defaults to 5. required: - url - eventTypes additionalProperties: false description: A new webhook endpoint. WebhookEndpointWithSecret: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object properties: secret: type: string pattern: ^whsec_[A-Za-z0-9_-]{43}$ description: >- The signing secret (`whsec_` plus 43 characters). Shown only in this response: store it now. Verify each delivery by computing HMAC-SHA256 over `.` with this whole string as the key and comparing it with a `v1` value of the `Centaur-Signature` header. required: - secret ErrorEnvelope: type: object properties: success: type: boolean enum: - false error: $ref: '#/components/schemas/Error' requestId: type: string example: c8e2c6e4-80dd-4ffc-9d66-4e31bf64c6b8 required: - success - error - requestId WebhookEventType: type: string enum: - trade_event.created - trade_event.deleted - feed_item.created - feed_item.updated - feed_item.deleted - positioning.trending.updated - positioning.specialist_ideas.updated - positioning.early_opportunities.updated - positioning.crowd_fade.updated - positioning.smart_money.updated - positioning.leaders_book.updated WebhookEndpoint: type: object properties: id: type: string format: uuid description: Endpoint ID. url: type: string description: The URL deliveries are sent to. description: type: - string - 'null' description: Your label for the endpoint, or null. eventTypes: type: array items: $ref: '#/components/schemas/WebhookEventType' description: Event types the endpoint subscribes to. filters: $ref: '#/components/schemas/WebhookEndpointFilters' status: $ref: '#/components/schemas/WebhookEndpointStatus' statusChangedAt: type: string format: date-time description: When `status` last changed. disabledReason: type: - string - 'null' description: >- Why the endpoint is `DISABLED`: your reason, `410_gone` (the endpoint answered 410), `sustained_failure` (it failed for about two hours), `unsafe_url`, or a note from Centaur. Null otherwise. maxInFlight: type: integer description: Maximum deliveries sent to this endpoint at the same time. consecutiveFailures: type: integer description: >- Failed attempts in a row since the last success. Reset by a success, a URL change or re-enabling. lastSuccessAt: type: - string - 'null' format: date-time description: >- When a delivery last succeeded, or null. During a burst of successes it is refreshed at most every 10 seconds. lastFailureAt: type: - string - 'null' format: date-time description: When a delivery attempt last failed, or null. lastSequence: type: integer description: >- The highest `sequence` assigned to a delivery of this endpoint so far. 0 before the first. secretRotatedAt: type: - string - 'null' format: date-time description: When the signing secret was last rotated, or null. previousSecretExpiresAt: type: - string - 'null' format: date-time description: >- Until this time, deliveries also carry a signature made with the previous secret, so you can switch secrets without dropping events. Null when there is no previous secret. createdAt: type: string format: date-time description: When the endpoint was created. updatedAt: type: string format: date-time description: When the endpoint was last changed. required: - id - url - description - eventTypes - filters - status - statusChangedAt - disabledReason - maxInFlight - consecutiveFailures - lastSuccessAt - lastFailureAt - lastSequence - secretRotatedAt - previousSecretExpiresAt - createdAt - updatedAt Error: type: object properties: code: type: string description: Stable machine-readable error code. example: UNAUTHORIZED message: type: string description: Human-readable explanation for the failure. example: Unauthorized details: description: Optional structured details for validation or input failures. required: - code - message WebhookEndpointFilters: type: object properties: traderIds: type: array items: type: integer exclusiveMinimum: 0 minItems: 1 maxItems: 100 description: >- Deliver only events of these trader IDs. Omit for no trader filtering. sourceIdentityIds: type: array items: type: string minLength: 1 description: >- Opaque platform-scoped source identity ID for the source account or channel. minItems: 1 maxItems: 100 description: >- Deliver only events from these opaque source identity IDs (the `source.identity.sourceIdentityId` values). Omit for no source filtering. assetIds: type: array items: type: integer exclusiveMinimum: 0 minItems: 1 maxItems: 100 description: Deliver only events on these asset IDs. Omit for no asset filtering. assetClasses: type: array items: type: string enum: - crypto - stocks - indices - commodities - fx minItems: 1 maxItems: 100 description: >- Deliver only events on assets of these classes: crypto, stocks, indices, commodities, or fx. Omit for no asset-class filtering. additionalProperties: false description: >- Subscription filters of a webhook endpoint. Omitting a filter means no filtering on it. WebhookEndpointStatus: type: string enum: - ACTIVE - PAUSED - DISABLED description: >- Endpoint state. `ACTIVE` receives deliveries. `PAUSED` holds new deliveries until you resume it, then releases them: they are claimed in order; arrival order is not guaranteed. `DISABLED` was turned off by you, by Centaur, or automatically after repeated failures (see `disabledReason`); new deliveries are held, and after you re-enable it you replay the range you need. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Centaur. x-default: ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.